From b60a316841cb9f0403946594c6615038c736be59 Mon Sep 17 00:00:00 2001 From: Michael Mathews Date: Sun, 25 Jul 2010 12:39:15 +0100 Subject: [PATCH] Cleaned up naming of required modules. --- main.js | 2 +- modules/jsdoc/doclet.js | 24 +++++++------ modules/jsdoc/name.js | 9 +++-- modules/jsdoc/opts.js | 6 ++-- modules/jsdoc/parser.js | 66 +++++++++++++++++----------------- modules/jsdoc/schema.js | 2 +- modules/jsdoc/src.js | 18 +++++----- modules/jsdoc/tag.js | 14 ++++---- modules/jsdoc/tagdictionary.js | 3 +- 9 files changed, 76 insertions(+), 68 deletions(-) diff --git a/main.js b/main.js index a665d5e8..70032bf5 100644 --- a/main.js +++ b/main.js @@ -51,7 +51,7 @@ }, opts, sourceFiles; - + app.opts = opts = jsdoc.opts.set(args); if (opts.help) { diff --git a/modules/jsdoc/doclet.js b/modules/jsdoc/doclet.js index 25518a2c..765e7e63 100644 --- a/modules/jsdoc/doclet.js +++ b/modules/jsdoc/doclet.js @@ -9,9 +9,11 @@ @module jsdoc/doclet */ (function() { - var name = require('jsdoc/name'), - parse_tag = require('jsdoc/tag'), - tagDictionary = require('jsdoc/tagdictionary'); + var jsdoc = { + name: require('jsdoc/name'), + tag: require('jsdoc/tag'), + tagDictionary: require('jsdoc/tagdictionary') + }; /** Factory that builds a Doclet object. @@ -31,7 +33,7 @@ commentSrc = unwrapComment(commentSrc); commentSrc = fixDesc(commentSrc); - tags = parse_tag.parse(commentSrc); + tags = jsdoc.tag.parse(commentSrc); try { preprocess(tags, meta); @@ -48,7 +50,7 @@ doclet.meta = meta; postprocess(doclet); - name.resolve(doclet); + jsdoc.name.resolve(doclet); return doclet } @@ -70,12 +72,12 @@ /** Set the name of the Doclet. @method Doclet#setName - @param {string name + @param {string} nameToSet */ Doclet.prototype.setName = function(nameToSet) { this.setTag('name', nameToSet); - nameToSet = name.resolve(this); + nameToSet = jsdoc.name.resolve(this); } /** @@ -85,7 +87,7 @@ @returns {*} The value of the found tag. */ Doclet.prototype.tagValue = function(tagName) { - var tagAbout = tagDictionary.lookUp(tagName); + var tagAbout = jsdoc.tagDictionary.lookUp(tagName); for (var i = 0, leni = this.tags.length; i < leni; i++) { if (this.tags[i].name === tagName) { if (tagAbout.isScalar && this.tags[i].value.push) { @@ -167,7 +169,7 @@ tag = this.tags[i]; tagName = tag.name; tagValue = {}; - tagAbout = tagDictionary.lookUp(tagName); + tagAbout = jsdoc.tagDictionary.lookUp(tagName); if (!tagAbout.isExported) { continue; } @@ -283,7 +285,7 @@ tagAbout; for (var i = 0; i < tags.length; i++) { - tagAbout = tagDictionary.lookUp(tags[i].name); + tagAbout = jsdoc.tagDictionary.lookUp(tags[i].name); if (tagAbout.setsDocletAttrib) { tags.addTag('attrib', tags[i].name); @@ -377,7 +379,7 @@ var tags = doclet.tags; for (var i = 0, leni = tags.length; i < leni; i++) { - tagAbout = tagDictionary.lookUp(tags[i].name); + tagAbout = jsdoc.tagDictionary.lookUp(tags[i].name); // class tags imply a constructor tag diff --git a/modules/jsdoc/name.js b/modules/jsdoc/name.js index da7bd038..13d58b57 100644 --- a/modules/jsdoc/name.js +++ b/modules/jsdoc/name.js @@ -11,8 +11,11 @@ (function() { var Token = Packages.org.mozilla.javascript.Token, - currentModule = '', - tagDictionary = require('jsdoc/tagdictionary'); + currentModule = ''; + + var jsdoc = { + tagDictionary: require('jsdoc/tagdictionary') + }; exports.setCurrentModule = function(moduleName) { currentModule = moduleName; @@ -83,7 +86,7 @@ // if name doesn't already have a docspace and needs one // the namespace should appear in the path but not the name - if (tagDictionary.lookUp(kind).setsDocletDocspace) { + if (jsdoc.tagDictionary.lookUp(kind).setsDocletDocspace) { if ( /^[a-z_$-]+:(\S+)/i.test(name) ) { name = RegExp.$1; } diff --git a/modules/jsdoc/opts.js b/modules/jsdoc/opts.js index 4715bd38..bc0cfc68 100644 --- a/modules/jsdoc/opts.js +++ b/modules/jsdoc/opts.js @@ -9,9 +9,11 @@ @requires common/args */ (function() { - var args = args || require('common/args'); + var common = { + args: require('common/args') + }; - var argsParser = new args.Parser(), + var argsParser = new common.args.Parser(), ourOptions, defaults = { template: 'default', diff --git a/modules/jsdoc/parser.js b/modules/jsdoc/parser.js index 4c20b475..db6ade9d 100644 --- a/modules/jsdoc/parser.js +++ b/modules/jsdoc/parser.js @@ -1,11 +1,13 @@ (function() { - var name = require('jsdoc/name'), - doclet = require('jsdoc/doclet'), - doclets = require('jsdoc/docset').doclets, - opts = require('jsdoc/opts'), - Token = Packages.org.mozilla.javascript.Token; - - exports.result = doclets; + var Token = Packages.org.mozilla.javascript.Token; + + var jsdoc = { + name: require('jsdoc/name'), + doclet: require('jsdoc/doclet'), + doclets: require('jsdoc/docset').doclets + }; + + exports.result = jsdoc.doclets; /** */ @@ -16,17 +18,17 @@ thisDocletPath = ''; // look for all comments that have names provided - if (node.type === Token.SCRIPT && node.comments) { + if (node.type === Token.SCRIPT && node.comments) { for each (var comment in node.comments.toArray()) { if (comment.commentType === Token.CommentType.JSDOC) { commentSrc = '' + comment.toSource(); if (commentSrc) { - thisDoclet = doclet.makeDoclet(commentSrc, comment, currentSourceName); + thisDoclet = jsdoc.doclet.makeDoclet(commentSrc, comment, currentSourceName); if ( thisDoclet.hasTag('name') && thisDoclet.hasTag('kind') ) { - doclets.addDoclet(thisDoclet); + jsdoc.doclets.addDoclet(thisDoclet); if (thisDoclet.tagValue('kind') === 'module') { - name.setCurrentModule( thisDoclet.tagValue('path') ); + jsdoc.name.setCurrentModule( thisDoclet.tagValue('path') ); } } } @@ -42,7 +44,7 @@ commentSrc = (node.jsDoc)? String(node.jsDoc) : ''; if (commentSrc) { - thisDoclet = doclet.makeDoclet(commentSrc, node, currentSourceName); + thisDoclet = jsdoc.doclet.makeDoclet(commentSrc, node, currentSourceName); thisDocletName = thisDoclet.tagValue('path'); if (!thisDoclet.hasTag('kind')) { // guess kind from the source code @@ -50,20 +52,20 @@ } if (!thisDocletName) { // guess name from the source code - thisDocletName = name.resolveInner(node.name, node, thisDoclet); + thisDocletName = jsdoc.name.resolveInner(node.name, node, thisDoclet); thisDoclet.setName(thisDocletName); - doclets.addDoclet(thisDoclet); + jsdoc.doclets.addDoclet(thisDoclet); } - name.refs.push([node, thisDoclet]); + jsdoc.name.refs.push([node, thisDoclet]); } else { // an uncommented function? // this thing may have commented members, so keep a ref to the thing but don't add it to the doclets list - thisDoclet = doclet.makeDoclet('[[undocumented]]', node, currentSourceName); + thisDoclet = jsdoc.doclet.makeDoclet('[[undocumented]]', node, currentSourceName); - nodeName = name.resolveThis(node.name, node, thisDoclet); + nodeName = jsdoc.name.resolveThis(node.name, node, thisDoclet); thisDoclet.setName(nodeName); - name.refs.push([ + jsdoc.name.refs.push([ node, thisDoclet ]); @@ -82,7 +84,7 @@ if (commentSrc) { commentSrc = '' + commentSrc; - thisDoclet = doclet.makeDoclet(commentSrc, node, currentSourceName); + thisDoclet = jsdoc.doclet.makeDoclet(commentSrc, node, currentSourceName); thisDocletName = thisDoclet.tagValue('name'); nodeKind = thisDoclet.tagValue('kind'); @@ -96,22 +98,22 @@ } if (!thisDocletName) { // guess name from the source code - nodeName = name.resolveThis(nodeName, node, thisDoclet); + nodeName = jsdoc.name.resolveThis(nodeName, node, thisDoclet); thisDoclet.setName(nodeName); - doclets.addDoclet(thisDoclet); + jsdoc.doclets.addDoclet(thisDoclet); } - name.refs.push([node.right, thisDoclet]); + jsdoc.name.refs.push([node.right, thisDoclet]); } else { // an uncommented objlit or anonymous function? // this thing may have commented members, so keep a ref to the thing but don't add it to the doclets list - thisDoclet = doclet.makeDoclet('[[undocumented]]', node, currentSourceName); - nodeName = name.resolveThis(nodeName, node, thisDoclet); + thisDoclet = jsdoc.doclet.makeDoclet('[[undocumented]]', node, currentSourceName); + nodeName = jsdoc.name.resolveThis(nodeName, node, thisDoclet); thisDoclet.setName(nodeName); - name.refs.push([ + jsdoc.name.refs.push([ node.right, thisDoclet ]); @@ -131,7 +133,7 @@ commentSrc = (counter++ === 0 && !n.jsDoc)? node.jsDoc : n.jsDoc; if (commentSrc) { - thisDoclet = doclet.makeDoclet('' + commentSrc, node, currentSourceName); + thisDoclet = jsdoc.doclet.makeDoclet('' + commentSrc, node, currentSourceName); thisDocletPath = thisDoclet.tagValue('path'); thisDocletName = thisDoclet.tagValue('name'); @@ -147,26 +149,26 @@ if (!thisDocletName) { thisDocletName = n.target.string; if (!thisDocletPath) { // guess path from the source code - thisDocletPath = name.resolveInner(thisDocletName, node, thisDoclet); + thisDocletPath = jsdoc.name.resolveInner(thisDocletName, node, thisDoclet); thisDoclet.setName(thisDocletPath); } else { thisDoclet.setName(thisDocletName); } - doclets.addDoclet(thisDoclet); + jsdoc.doclets.addDoclet(thisDoclet); } - if (val) { name.refs.push([val, thisDoclet]); } + if (val) { jsdoc.name.refs.push([val, thisDoclet]); } } else { // an uncommented objlit or anonymous function? var nodeName = nodeToString(n.target); // this thing may have commented members, so keep a ref to the thing but don't add it to the doclets list - thisDoclet = doclet.makeDoclet('[[undocumented]]', n.target, currentSourceName); + thisDoclet = jsdoc.doclet.makeDoclet('[[undocumented]]', n.target, currentSourceName); - nodeName = name.resolveInner(nodeName, n.target, thisDoclet); + nodeName = jsdoc.name.resolveInner(nodeName, n.target, thisDoclet); thisDoclet.setName(nodeName); - if (val) name.refs.push([val, thisDoclet]); + if (val) jsdoc.name.refs.push([val, thisDoclet]); } } diff --git a/modules/jsdoc/schema.js b/modules/jsdoc/schema.js index c5549e94..566f9754 100644 --- a/modules/jsdoc/schema.js +++ b/modules/jsdoc/schema.js @@ -33,7 +33,7 @@ exports.jsdocSchema = { "kind": { "type": "string", "maxItems": 1, - "enum": ["constructor", "module", "event", "namespace", "method", "property", "enum", "class", "interface", "constant", "file"] + "enum": ["constructor", "module", "event", "namespace", "method", "property", "enum", "class", "interface", "constant", "file", "version"] }, "access": { "type": "string", diff --git a/modules/jsdoc/src.js b/modules/jsdoc/src.js index 6505a8f4..2ddd2f1b 100644 --- a/modules/jsdoc/src.js +++ b/modules/jsdoc/src.js @@ -1,34 +1,32 @@ /** - @overview Find source files to be parsed for docs. + @file Find source files to be parsed for docs. @author Michael Mathews @license Apache License 2.0 - See file 'LICENSE.md' in this project. - */ +*/ /** @module jsdoc/src - @namespace jsdoc.src - @requires common/fs + @requires module:common/fs */ -var jsdoc = jsdoc || {}; -jsdoc.src = (typeof exports === 'undefined')? {} : exports; // like commonjs (function() { - var fs = fs || require('common/fs'); + var common = { + fs: require('common/fs') + }; /** Recursively searches the given searchPaths for js files. - @method getFilePaths @param {Array.} searchPaths @param {number} [depth=1] */ - jsdoc.src.getFilePaths = function(searchPaths, depth) { + exports.getFilePaths = function(searchPaths, depth) { var filePaths = []; searchPaths = searchPaths || []; depth = depth || 1; searchPaths.forEach(function($) { - filePaths = filePaths.concat(fs.ls($, depth)); + filePaths = filePaths.concat(common.fs.ls($, depth)); }); // TODO: allow user-defined filtering of files diff --git a/modules/jsdoc/tag.js b/modules/jsdoc/tag.js index d288fe54..dfcf57a6 100644 --- a/modules/jsdoc/tag.js +++ b/modules/jsdoc/tag.js @@ -9,8 +9,10 @@ @module jsdoc/tag */ (function() { - var jsdoc_type = require('jsdoc/type'), - tagDictionary = require('jsdoc/tagdictionary'); + var jsdoc = { + type: require('jsdoc/type'), + tagDictionary: require('jsdoc/tagdictionary') + }; exports.fromText = function(tagText) { var tag = new Tag(tagText); @@ -46,12 +48,12 @@ if (parts) { this.name = (parts[1] || '').toLowerCase(); // like @name - this.name = tagDictionary.resolveSynonyms(this.name); + this.name = jsdoc.tagDictionary.resolveSynonyms(this.name); tagText = parts[2] || ''; // all the rest of the tag // now that we know who you are, tell us a little about yourself... - var tagAbout = tagDictionary.lookUp(this.name); + var tagAbout = jsdoc.tagDictionary.lookUp(this.name); if (!tagAbout.keepsWhitespace) { tagText = trim(tagText); @@ -64,7 +66,7 @@ /*any*/ value, /*?boolean*/ optional, /*?boolean*/ nullable - ] = jsdoc_type.parse(this.value); + ] = jsdoc.type.parse(this.value); if (type && type.length) { this.type = type; } @@ -109,7 +111,7 @@ tagName = tagName.name; } - var tagAbout = tagDictionary.lookUp(tagName); + var tagAbout = jsdoc.tagDictionary.lookUp(tagName); if (tagAbout.isScalar && this.hasTag(tagName)) { return false; } diff --git a/modules/jsdoc/tagdictionary.js b/modules/jsdoc/tagdictionary.js index 65de21e4..a2ee8492 100644 --- a/modules/jsdoc/tagdictionary.js +++ b/modules/jsdoc/tagdictionary.js @@ -33,8 +33,7 @@ 'throws': 'exception', 'class': 'classdesc', 'this': 'thisobj', - 'preserve': 'ignore', - 'license': 'ignore' + 'preserve': 'ignore' }; tagDictionary.resolveSynonyms = function(name) {