/tags/jsdoc_toolkit-1.3.3/app/JsDoc.js

 1/**
 2 * @fileOverview
 3 * @name JsDoc Toolkit
 4 * @author Michael Mathews micmath@gmail.com
 5 * @url $HeadURL: http://jsdoc-toolkit.googlecode.com/svn/tags/jsdoc_toolkit-1.3.3/app/JsDoc.js $
 6 * @revision $Id: JsDoc.js 276 2007-10-16 23:32:57Z micmath $
 7 * @license <a href="http://en.wikipedia.org/wiki/MIT_License">X11/MIT License</a>
 8 *          (See the accompanying README file for full details.)
 9 */
10
11/** @class Handle reporting messages to the user
12	@static
13*/
14LOG = {
15	warn: function(msg, e) {
16		if (e) msg = e.fileName+", line "+e.lineNumber+": "+msg;
17		
18		msg = ">> WARNING: "+msg;
19		if (LOG.out) LOG.out.write(msg+"\n");
20		else print(msg);
21	},
22
23	inform: function(msg) {
24		msg = " > "+msg;
25		if (LOG.out) LOG.out.write(msg+"\n");
26		else print(msg);
27	}
28};
29
30/**
31	@class An automated documentation publishing system for JavaScript.
32	@static
33	@author Michael Mathews <a href="mailto:micmath@gmail.com">micmath@gmail.com</a>
34*/
35JsDoc = {
36	VERSION: "1.3.3",
37	
38	/**
39	 * Print out the expected usage syntax for this script on the command
40	 * line. This is called automatically by using the -h/--help option.
41	 */
42	usage: function() {
43		print("USAGE: java -jar app/js.jar app/jsdoc.js [OPTIONS] <SRC_DIR> <SRC_FILE> ...");
44		print("");
45		print("OPTIONS:");
46		print("  -t=<PATH> or --template=<PATH>\n          Required. Use this template to format the output.\n");
47		print("  -d=<PATH> or --directory=<PATH>\n          Output to this directory (defaults to js_docs_out).\n");
48		print("  -r=<DEPTH> or --recurse=<DEPTH>\n          Descend into src directories.\n");
49		print("  -x=<EXT>[,EXT]... or --ext=<EXT>[,EXT]...\n          Scan source files with the given extension/s (defaults to js).\n");
50		print("  -a or --allfunctions\n          Include all functions, even undocumented ones.\n");
51		print("  -A or --Allfunctions\n          Include all functions, even undocumented, underscored ones.\n");
52		print("  -p or --private\n          Include symbols tagged as private.\n");
53		print("  -o=<PATH> or --out=<PATH>\n          Print log messages to a file (defaults to stdout).\n");
54		print("  -h or --help\n          Show this message and exit.\n");
55		
56		java.lang.System.exit(0);
57	},
58	
59	/**
60	 * @param {string[]} srcFiles Paths to files to be documented
61	 * @return {DocFile[]}
62	 */
63	parse: function(srcFiles) {
64		var files = [];
65		
66		if (typeof srcFiles == "string") srcFiles = [srcFiles];	
67		var parser = new JsParse();
68		
69		srcFiles = srcFiles.sort();
70		
71		var docs = new DocFileGroup();
72		
73		// handle setting up relationships between symbols here
74		for (var f = 0; f < srcFiles.length; f++) {
75			var srcFile = srcFiles[f];
76			
77			LOG.inform("Tokenizing: file "+(f+1)+", "+srcFile);
78			var src = IO.readFile(srcFile);
79			
80			var tokens = new TokenReader(src).tokenize();
81			LOG.inform("\t"+tokens.length+" tokens found.");
82			var ts = new TokenStream(tokens);
83			
84			var file = new DocFile(srcFile);
85			parser.parse(ts);
86			LOG.inform("\t"+parser.symbols.length+" symbols found.");
87			
88			file.addSymbols(parser.symbols, JsDoc.opt);
89			if (parser.overview) file.overview = parser.overview;
90			
91			docs.addDocFile(file);
92		}
93		return docs;
94	}
95};
96
97/** Override this dummy function in your template. */
98function publish() {}