Refactor: moved setlongname from jsdoc/name to jsdoc/doclet. Added docs to jsdoc/doclet.

modules/jsdoc/doclet.js

@@ -1,12 +1,14 @@
+/**
+    @overview
+    @author Michael Mathews <micmath@gmail.com>
+	@license Apache License 2.0 - See file 'LICENSE.md' in this project.
+ */
+
 /**
 	@module jsdoc/doclet
-	
 	@requires jsdoc/tag
-	@requires jsdoc/tag/dictionary
 	@requires jsdoc/name
-
+	@requires jsdoc/tag/dictionary
-	@author Michael Mathews <micmath@gmail.com>
-	@license Apache License 2.0 - See file 'LICENSE.md' in this project.
  */
 (function() {
 	var jsdoc = {
@@ -19,6 +21,8 @@
 	
 	/**
 	    @constructor
+	    @param {string} docletSrc - The raw source code of the jsdoc comment.
+	    @param {object} meta - Properties describing the code related to this comment.
 	 */
 	exports.Doclet = function (docletSrc, meta) {
 	    var newTags = [];
@@ -36,7 +40,6 @@
 	    }
 	    
 	    this.postProcess();
-	    
 	}
 	
 	function addMeta(meta) {
@@ -57,8 +60,7 @@
 	exports.Doclet.prototype.postProcess = function() {
 	    if (!this.preserveName) { jsdoc.name.resolve(this); }
 	    if (this.name && !this.longname) {
-	        this.longname = this.name;
+	        this.setLongname(this.name);  
-	        jsdoc.name.setLongname(this, this.name);  
 	    }
 	    if (!this.kind && this.meta && this.meta.code) {
 	        this.addTag( 'kind', codetypeToKind(this.meta.code.type) );
@@ -92,6 +94,16 @@
 	    this.memberof = sid;
 	}
 	
+	/** Set the `longname` property of this doclet.
+	    @param {string} name
+	*/
+	exports.Doclet.prototype.setLongname = function(name) {
+	    this.longname = name;
+        if (jsdoc.tag.dictionary.isNamespace(this.kind)) {
+	        this.longname = jsdoc.name.applyNamespace(this.longname, this.kind);
+	    }
+	}
+	
 	/** Add a symbol to this doclet's `borrowed` array.
 	    @param {string} source - The longname of the symbol that is the source.
 	    @param {string} target - The name the symbol is being assigned to.
@@ -101,6 +113,9 @@
         this.borrowed.push( {from: source, as: (target||source)} );
 	}
 	
+	/** Add a symbol to this doclet's `augments` array.
+	    @param {string} base - The longname of the base symbol.
+	*/
 	exports.Doclet.prototype.augment = function(base) {
 	    if (!this.augments) { this.augments = []; }
         this.augments.push(base);

modules/jsdoc/name.js

@@ -1,12 +1,7 @@
-/*
-    @overview
-    @author Michael Mathews <micmath@gmail.com>
-    @license Apache License 2.0 - See file 'LICENSE.md' in this project.
- */
-
 /**
-    Functionality relating to symbol name manipulation.
+    A collection of functions relating to JSDoc symbol name manipulation.
     @module jsdoc/name
+    @requires jsdoc/tag/dictionary
  */
 (function() {
     var jsdoc = {
@@ -18,10 +13,8 @@
         Token  = Packages.org.mozilla.javascript.Token;
         
     /**
-        Resolves the sid, memberof and name values.
+        Resolves the longname, memberof, variation and name values of the given doclet.
-        @method module:jsdoc/name.resolve
+        @param {module:jsdoc/doclet.Doclet} doclet
-        @param {Doclet} doclet
-        @throws {invalidArgumentException}
      */
     exports.resolve = function(doclet) {
 
@@ -59,11 +52,11 @@
         }
         
         if (about.longname && !doclet.longname) {
-            exports.setLongname(doclet, about.longname);
+            doclet.setLongname(about.longname);
         }
         
         if (doclet.scope === 'global') { // via @global tag?
-            exports.setLongname(doclet, doclet.name);
+            doclet.setLongname(doclet.name);
             delete doclet.memberof;
         }
         else if (about.scope) {
@@ -73,7 +66,7 @@
             if (doclet.name && doclet.memberof && !doclet.longname) {
                 doclet.scope = 'static'; // default scope when none is provided
                 
-                exports.setLongname(doclet, doclet.memberof + scopeToPunc[doclet.scope] + doclet.name);
+                doclet.setLongname(doclet.memberof + scopeToPunc[doclet.scope] + doclet.name);
             }
         }
         
@@ -82,13 +75,6 @@
         }
     }
     
-    exports.setLongname = function(doclet, name) {
-        doclet.longname = name;
-        if (jsdoc.tagDictionary.isNamespace(doclet.kind)) {
-	        doclet.longname = exports.applyNamespace(doclet.longname, doclet.kind);
-	    }
-    }
-    
     function quoteUnsafe(name, kind) { // docspaced names may have unsafe characters which need to be quoted by us
         if ( (jsdoc.tagDictionary.lookUp(kind).setsDocletDocspace) && /[^$_a-zA-Z0-9\/]/.test(name) ) {
             if (!/^[a-z_$-\/]+:\"/i.test(name)) {
@@ -125,6 +111,8 @@
     /**
         Given a longname like "a.b#c(2)", slice it up into ["a.b", "#", 'c', '2'],
         representing the memberof, the scope, the name, and variation.
+        @param {string} longname
+        @returns {object} Representing the properties of the given name.
      */
     exports.shorten = function(longname) {
         //// quoted strings in a longname are atomic, convert to tokens