diff --git a/modules/common/fs.js b/modules/common/fs.js index b749c99d..851d4aac 100644 --- a/modules/common/fs.js +++ b/modules/common/fs.js @@ -106,6 +106,42 @@ return _allFiles; } + exports.copyFile = function(inFile, outDir, fileName) { + if (fileName == null) fileName = exports.toFile(inFile); + + outDir = exports.toDir(outDir); + + var inFile = new File(inFile); + var outFile = new File(outDir+slash+fileName); + + var bis = new Packages.java.io.BufferedInputStream(new Packages.java.io.FileInputStream(inFile), 4096); + var bos = new Packages.java.io.BufferedOutputStream(new Packages.java.io.FileOutputStream(outFile), 4096); + var theChar; + while ((theChar = bis.read()) != -1) { + bos.write(theChar); + } + bos.close(); + bis.close(); + } + + exports.toDir = function(path) { + var file = new File(path); + + if (file.isDirectory()){ + return path; + } + + var parts = path.split(/[\\\/]/); + parts.pop(); + + return parts.join(slash); + } + + exports.toFile = function(path) { + var parts = path.split(/[\\\/]/); + return parts.pop(); + } + exports.mkPath = function(/**Array*/ path) { if (path.constructor != Array) path = path.split(/[\\\/]/); var make = ""; @@ -118,8 +154,9 @@ } exports.makeDir = function(/**string*/ path) { - (new File(path)).mkdir(); - }, + var dirPath = (exports.toDir(path)); + (new File(dirPath)).mkdir(); + } // fix multiple slashes, like one//two function fixSlash(path) { diff --git a/modules/jsdoc/src/parser.js b/modules/jsdoc/src/parser.js index 6661e233..a30f75c7 100644 --- a/modules/jsdoc/src/parser.js +++ b/modules/jsdoc/src/parser.js @@ -1,8 +1,8 @@ /** - @module jsdoc/src/parser - @requires module:common/util - @requires module:common/fs - @requires module:common/events + * @module jsdoc/src/parser + * @requires common/util + * @requires common/fs + * @requires common/events */ (function() { @@ -11,24 +11,31 @@ currentSourceName = ''; /** - @constructor module:jsdoc/src/parser.Parser - @mixes module:common/events + * @class + * @mixes module:common/events + * + * @example + * var jsdocParser = new (require('jsdoc/src/parser').Parser)(); */ - var Parser = exports.Parser = function() { + exports.Parser = function() { this._resultBuffer = []; this.refs = {}; } - require('common/util').mixin(Parser.prototype, require('common/events')); + require('common/util').mixin(exports.Parser.prototype, require('common/events')); /** - @method module:jsdoc/src/parser.Parser#parse - @param {Array} sourceFiles - @param {string} [encoding=utf8] - @fires jsdocCommentFound - @fires symbolFound - @fires newDoclet - @fires fileBegin - @fires fileComplete + * @param {Array} sourceFiles + * @param {string} [encoding=utf8] + * + * @fires jsdocCommentFound + * @fires symbolFound + * @fires newDoclet + * @fires fileBegin + * @fires fileComplete + * + * @example + * var myFiles = ['file1.js', 'file2.js']; + * var docs = jsdocParser.parse(myFiles); */ exports.Parser.prototype.parse = function(sourceFiles, encoding) { const SCHEMA = 'javascript:'; @@ -62,23 +69,21 @@ } /** - @method module:jsdoc/src/parser.Parser#results - @returns {Array} The accumulated results of any calls to parse. + * @returns {Array} The accumulated results of any calls to parse. */ exports.Parser.prototype.results = function() { return this._resultBuffer; } /** - @method module:jsdoc/src/parser.Parser#addResult + * @param {Object} The parse result to add to the result buffer. */ exports.Parser.prototype.addResult = function(o) { this._resultBuffer.push(o); } /** - Empty any accumulated results of calls to parse. - @method module:jsdoc/src/parser.Parser#clear + * Empty any accumulated results of calls to parse. */ exports.Parser.prototype.clear = function() { currentParser = null; @@ -86,9 +91,7 @@ this._resultBuffer = []; } - /** - @private - */ + /** @private */ exports.Parser.prototype._parseSourceCode = function(sourceCode, sourceName) { currentSourceName = sourceName; @@ -114,14 +117,15 @@ } /** - Given a node, determine what the node is a member of. + * Given a node, determine what the node is a member of. + * @param {astnode} node */ - exports.Parser.prototype.astnodeToMemberof = function(astnode) { + exports.Parser.prototype.astnodeToMemberof = function(node) { var memberof = {}; - if (astnode.type === Token.VAR || astnode.type === Token.FUNCTION) { - if (astnode.enclosingFunction) { // an inner var or func - memberof.id = 'astnode'+astnode.enclosingFunction.hashCode(); + if (node.type === Token.VAR || node.type === Token.FUNCTION) { + if (node.enclosingFunction) { // an inner var or func + memberof.id = 'astnode'+node.enclosingFunction.hashCode(); memberof.doclet = this.refs[memberof.id]; if (!memberof.doclet) { return '~'; @@ -130,7 +134,7 @@ } } else { - memberof.id = 'astnode'+astnode.parent.hashCode(); + memberof.id = 'astnode'+node.parent.hashCode(); memberof.doclet = this.refs[memberof.id]; if (!memberof.doclet) return ''; // global? return memberof.doclet.longname||memberof.doclet.name; @@ -138,7 +142,9 @@ } /** - Resolve what "this" refers too, relative to a node + * Resolve what "this" refers too, relative to a node. + * @param {astnode} node - The "this" node + * @returns {string} The longname of the enclosing node. */ exports.Parser.prototype.resolveThis = function(node) { var memberof = {}; @@ -186,9 +192,9 @@ } /** - Resolve what function a var is limited to. - @param {astnode} node - @param {string} basename The leftmost name in the long name: in foo.bar.zip the basename is foo. + * Resolve what function a var is limited to. + * @param {astnode} node + * @param {string} basename The leftmost name in the long name: in foo.bar.zip the basename is foo. */ exports.Parser.prototype.resolveVar = function(node, basename) { var doclet, @@ -205,9 +211,7 @@ return this.resolveVar(enclosingFunction, basename); } - /** - @private - */ + /** @private */ function visitNode(node) { var e, commentSrc; @@ -312,7 +316,7 @@ currentParser.refs['astnode'+e.code.node.hashCode()] = e.doclet; // allow lookup from value => doclet } } - else if (node.type == Token.FUNCTION/* && String(node.name) !== ''*/) { + else if (node.type == Token.FUNCTION) { e = { id: 'astnode'+node.hashCode(), // the id of the COLON node comment: String(node.jsDoc||'@undocumented'), @@ -329,12 +333,10 @@ } if (e.doclet) { -//dump(e.code.node.hashCode(), e.code, e.code.node.enclosingFunction? e.code.node.enclosingFunction.hashCode() : 'global') currentParser.refs['astnode'+e.code.node.hashCode()] = e.doclet; // allow lookup from value => doclet } else if (!currentParser.refs['astnode'+e.code.node.hashCode()]) { // keep references to undocumented anonymous functions too as they might have scoped vars currentParser.refs['astnode'+e.code.node.hashCode()] = { - //name: '', longname: '', meta: { code: e.code } }; @@ -344,9 +346,7 @@ return true; } - /** - @private - */ + /** @private */ function parserFactory() { var cx = Packages.org.mozilla.javascript.Context.getCurrentContext(); @@ -360,8 +360,8 @@ } /** - Attempts to find the name and type of the given node. - @private + * Attempts to find the name and type of the given node. + * @private */ function aboutNode(node) { about = {}; @@ -408,9 +408,7 @@ return about; } - /** - @private - */ + /** @private */ function nodeToString(node) { var str; @@ -444,9 +442,7 @@ return '' + str; }; - /** - @private - */ + /** @private */ function getTypeName(node) { var type = ''; @@ -457,9 +453,7 @@ return type; } - /** - @private - */ + /** @private */ function isValidJsdoc(commentSrc) { return commentSrc.indexOf('/***') !== 0; /*** ignore comments that start with many stars ***/ } diff --git a/package.json b/package.json index 9547be1e..ae59bd47 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "name": "jsdoc", "version": "3.0.0beta1", - "revision": "2011-02-08-2004", + "revision": "2011-02-11-2113", "description": "An automatic documentation generator for javascript.", "keywords": [ "documentation", "javascript" ], "licenses": [ diff --git a/templates/default/publish.js b/templates/default/publish.js index 87347a80..cc322ce7 100644 --- a/templates/default/publish.js +++ b/templates/default/publish.js @@ -53,6 +53,7 @@ doclet.hasReturns = doclet.returns && doclet.returns.length > 0; doclet.hasBorrowed = doclet.borrowed && doclet.borrowed.length > 0; doclet.hasExceptions = doclet.exceptions && doclet.exceptions.length > 0; + doclet.hasExamples = doclet.examples && doclet.examples.length > 0; summarize(doclet); }); @@ -65,6 +66,7 @@ returnsTemplate: fs.read(BASEDIR + 'templates/default/tmpl/returns.mustache'), methodsTemplate: fs.read(BASEDIR + 'templates/default/tmpl/methods.mustache'), propertiesTemplate: fs.read(BASEDIR + 'templates/default/tmpl/properties.mustache'), + examplesTemplate: fs.read(BASEDIR + 'templates/default/tmpl/example.mustache'), namespacesTemplate: fs.read(BASEDIR + 'templates/default/tmpl/namespaces.mustache'), classesTemplate: fs.read(BASEDIR + 'templates/default/tmpl/classes.mustache'), @@ -167,6 +169,17 @@ } fs.mkPath(outdir); + // copy static files to outdir + var fromDir = BASEDIR + 'templates/default/static', + staticFiles = fs.ls(fromDir, 3); + staticFiles.forEach(function(fileName) { + var toDir = fs.toDir(fileName.replace(fromDir, outdir)); + fs.mkPath(toDir); + fs.copyFile(fileName, toDir); + }); + + + // containers generate('Modules', modules, 'modules.html'); generate('Classes', classes, 'classes.html'); diff --git a/templates/default/static/styles/jsdoc-default.css b/templates/default/static/styles/jsdoc-default.css new file mode 100644 index 00000000..0cf7841f --- /dev/null +++ b/templates/default/static/styles/jsdoc-default.css @@ -0,0 +1,233 @@ +.kind { font-style: italic; } + +.constructor, .mixin, .namespace +{ + font-weight: bold; + color: #780000; +} + +.property { color: #666; } +.function { color: #666; } +.access { color: #666; } + +h1, h2, h3, h4, h5, h6 +{ + font-family: "Bitstream Vera Sans", "DejaVu Sans", "Trebuchet MS", Verdana, "Verdana Ref", sans serif; + font-weight: bold; +} + +.page-title +{ + font-family: "Bitstream Vera Sans", "DejaVu Sans", "Trebuchet MS", Verdana, "Verdana Ref", sans serif; + font-size: 3.5em; + font-weight: bolder; + margin: 0 0 0.1em; + color: #FFF; +} + +.section-title +{ + font-size: 2.5em; + margin: 0; + color: #798D3E; +} + +section +{ + border: 1px solid #ccc; + border-radius: 15px; + -moz-border-radius: 8px; + display: block; + padding: 0.75em 0.5em 0.5em 1em; + margin: 0.5em 0.5em 1em 1em; + background-color: #fff; + color: #000; +} + +.subsection-title +{ + font-size: 1.9em; + margin: 0.5em 0 1em; + color: #000; +} + +.method-title, .class-title +{ + font-size: 1.7em; + margin: 0 0 1em 1em; + color: #7B1A3F; +} + +.detail-list { list-style-type: none; } + +html +{ + /* stops IE resizing fonts by a massive amount */ + font-size: 100%; +} + +body +{ + /* fixes monospace font sizes in webkit */ + /* following line is picked up by IE6 & 7, which cannot resize pixel-based font sizes */ + *font-size: 62.5%; + font-size: 0.8em; + font-family: verdana, sans-serif; + /*overflow: hidden;*/ + zoom: 1; + /*background: url(images/pagebg.png) 0 73px repeat-x;*/ + color: #eee; + background-color: #22252a; +} + +a:link, a:visited +{ + color: #356a8b; + text-decoration: none; + border-bottom: 1px dotted #356a8b; +} + +a:hover, a:active +{ + color: #298FB2; + border-color: #298FB2; + border-bottom-style: solid; +} + +a.image { border: 0; } + +p +{ + margin: 0 0 1em 0; + line-height: 1.5; +} + +code { font-family: Consolas, "Andale Mono WT", "Andale Mono", "Lucida Console", "Lucida Sans Typewriter", "DejaVu Sans Mono", "Bitstream Vera Sans Mono", "Liberation Mono", "Nimbus Mono L", Monaco, "Courier New", Courier, monospace; } + +dl.params dt +{ + border-top: 1px solid #b2b1b1; + color: #298FB2; + font-weight: bold; + padding-top: 8px; + margin-bottom: 5px; + font-size: 1.1em; + float: none; + overflow: visible; + zoom: 0; +} + +dl.params dt.first +{ + border-top: none; + padding-top: 0; + margin-top: 0; +} + +dl.params dd +{ + border-width: 0; + margin-bottom: 16px; +} + +dl.param-properties +{ + font-style: italic; + overflow: hidden; + zoom: 1; + font-size: 0.9em; + margin: 1em 0; +} + +dl.param-properties dt span, +dl.param-properties dd +{ + color: #555; + float: left; + margin: 0; + padding: 0; + display: inline; + margin-bottom: 5px; + font-size: 1em; + border: none; +} + +dl.param-properties dt +{ + clear: both; + display: inline; + font-size: 1em; + padding: 0; + float: none; + overflow: visible; + zoom: 0; +} + +dl.param-properties dt span +{ + width: 85px; + clear: both; +} + +.no-docs +{ + font-style: italic; + font-weight: lighter; + color: #666; +} + +.property { margin-left: 30px; } + +.property-head +{ + margin-left: -20px; + display: block; + line-height: 1.2em; +} + +.property-name +{ + float: left; + margin: 0; + padding: 0 10px 0 0; + font-style: italic; + font-weight: bold; + font-size: 1.2em; + color: #4782B5; +} + +.property-summary +{ + color: #999; + font-size: 1em; +} + +.property-details +{ + clear: both; + overflow: hidden; +} + +.property-details dt +{ + font-weight: bold; + margin-bottom: 4px; + padding-left: 10px; + clear: left; + float: left; +} + +.property-details dd { padding-left: 60px; } +.property-deprecated { text-decoration: line-through; } + +.example-code +{ + padding: 2px 2px 2px 10px; + margin-right: 24px; + color: #fff; + background-color: #444; + border-radius: 2px; + -moz-border-radius: 2px; +} + +.yesDef { text-indent: -5000px; } \ No newline at end of file diff --git a/templates/default/static/styles/node-dark.css b/templates/default/static/styles/node-dark.css new file mode 100644 index 00000000..234e127d --- /dev/null +++ b/templates/default/static/styles/node-dark.css @@ -0,0 +1,26 @@ +.sh_sourceCode { + + font-weight: normal; + font-style: normal; +} + +.sh_sourceCode .sh_symbol , .sh_sourceCode .sh_cbracket { + color: #fff; +} + +.sh_sourceCode .sh_keyword +{ + font-style: italic; + color: #ECDDAA; +} + +.sh_sourceCode .sh_string, .sh_sourceCode .sh_regexp, .sh_sourceCode .sh_number, +.sh_sourceCode .sh_specialchar +{ + color: #B0C4DE; +} + +.sh_sourceCode .sh_comment { + color: #777; +} + diff --git a/templates/default/tmpl/container.mustache b/templates/default/tmpl/container.mustache index b1b7218d..34692572 100644 --- a/templates/default/tmpl/container.mustache +++ b/templates/default/tmpl/container.mustache @@ -4,244 +4,13 @@ JSDoc: {{title}} - + @@ -308,5 +77,6 @@ {{/docs}} + \ No newline at end of file diff --git a/templates/default/tmpl/example.mustache b/templates/default/tmpl/example.mustache new file mode 100644 index 00000000..089ac843 --- /dev/null +++ b/templates/default/tmpl/example.mustache @@ -0,0 +1,12 @@ +
+
Example
+
+
+ {{#examples}} +
+
+ 
{{.}}
+
+
+ {{/examples}} +
diff --git a/templates/default/tmpl/methods.mustache b/templates/default/tmpl/methods.mustache index 058a8e76..b7e621b8 100644 --- a/templates/default/tmpl/methods.mustache +++ b/templates/default/tmpl/methods.mustache @@ -8,7 +8,7 @@
Synopsis:
- 
{{synopsis}}
+ 
{{synopsis}}
{{#hasParams}}
Parameters:
@@ -24,6 +24,10 @@
Returns:
{{>returnsTemplate}} {{/hasReturns}} + + {{#hasExamples}} + {{>examplesTemplate}} + {{/hasExamples}}
diff --git a/templates/default/tmpl/properties.mustache b/templates/default/tmpl/properties.mustache index e3763428..341b5384 100644 --- a/templates/default/tmpl/properties.mustache +++ b/templates/default/tmpl/properties.mustache @@ -81,17 +81,8 @@ {{/defaultvalue}} - {{#examples}} -
- Example -
-
-
-
- 
{{.}}
-
-
-
- {{/examples}} + {{#hasExamples}} + {{>examplesTemplate}} + {{/hasExamples} \ No newline at end of file