Improvements to default template: added navigation.

git-svn-id: https://jsdoc.googlecode.com/svn/trunk/@19 d5942f49-e6af-b5c1-9d01-85772c7ca168

modules/jsdoc/name.js

@@ -78,10 +78,15 @@
         if (about.variation) {
             doclet.variation = about.variation;
         }
-
-//dump('doclet', doclet);
     }
 
+    /**
+        @inner
+        @memberof module:jsdoc/name
+        @param {string} name
+        @param {string} kind
+        @returns {string} The name with unsafe names enclosed in quotes.
+     */
     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)) {

modules/jsdoc/src/parser.js

@@ -12,7 +12,7 @@
 
     /** 
      * @class
-     * @mixes module:common/events.*
+     * @mixes module:common/events
      * 
      * @example <caption>Create a new parser.</caption>
      * var jsdocParser = new (require('jsdoc/src/parser').Parser)();

modules/jsdoc/src/scanner.js

@@ -15,7 +15,7 @@
 
 	/**
 	    @constructor
-	    @mixes module:common.events.*
+	    @mixes module:common.events
 	 */
 	exports.Scanner = function() {
 	}

modules/jsdoc/tag/dictionary/definitions.js

@@ -280,7 +280,7 @@
             }
         });
 
-        dictionary.defineTag('overload', {
+/*TODO?*/dictionary.defineTag('overload', {
             mustHaveValue: true,
             onTagged: function(doclet, tag) {
                 setDocletKindToTitle(doclet, tag);
@@ -385,6 +385,13 @@
             }
         });
 
+        dictionary.defineTag('summary', {
+            mustHaveValue: true,
+            onTagged: function(doclet, tag) {
+                doclet.summary = tag.value;
+            }
+        });
+
         dictionary.defineTag('this', {
             mustHaveValue: true,
             onTagged: function(doclet, tag) {
@@ -404,7 +411,10 @@
                 return text;
             },
             onTagged: function(doclet, tag) {
-                if (tag.value.type) { doclet.type = tag.value.type; }
+                if (tag.value.type) {
+                    doclet.type = tag.value.type;
+                    doclet.addTag('returns', tag.text); // for backwards compatibility we allow @type for functions to imply return type
+                }
             }
         });
 

modules/jsdoc/tag/validator.js

@@ -10,7 +10,7 @@
 	var dictionary = require('jsdoc/tag/dictionary');
 
 	/**
-	    @constructor
+	    Validate the given tag.
 	 */
 	exports.validate = function(tag, meta) {
 	    var tagDef = dictionary.lookUp(tag.title);

package.json

@@ -1,7 +1,7 @@
 {
 	"name": "jsdoc",
 	"version": "3.0.0beta1",
-	"revision": "2011-02-24-1703",
+	"revision": "2011-02-25-1216",
 	"description": "An automatic documentation generator for javascript.",
 	"keywords": [ "documentation", "javascript" ],
 	"licenses": [

templates/default/publish.js

@@ -22,6 +22,7 @@
             }
             partialData.render = arguments.callee;
             partialData.find = find;
+            partialData.linkto = linkto;
             partialData.htmlsafe = htmlsafe;
 
             return renderFunction.call(partialData, partialData);
@@ -35,38 +36,7 @@
         function htmlsafe(str) {
             return str.replace(/</g, '&lt;');
         }
-
-//         var helpers = {
-//             linkTo: function() {
-//                 return function(text, render) {
-//                     var linkTo,
-//                         text = render(text);
-//     
-//                     if ( !data.find({longname: text}).length ) { return text; }
-//                     
-//                     linkTo = text.replace(/#/g, '%23');
-//                     return '<a href="#' + linkTo + '">' + text + '</a>';
-//                 }
-//             }
-//         };
-
-        function summarize(doclet) {
-            var desc = doclet.description || '';
-
-            desc = desc.replace(/<\/?p>/gi, ''); // full text may be HTML, remove P wrapper
-            desc = desc.trim();
-
-            var m;
 
-            if ( m = /^([\s\S]+?)(?:\n|\r|\f|<br>|$)+([\s\S]*)$/.exec(desc) ) {
-                doclet.summary = m[1];
-                doclet.description = m[2]? m[2] : '';
-            }
-
-            doclet.signature = '';
-            doclet.attribs = '';
-        }
-
         function addSignatureParams(f) {
             var pnames = [];
             if (f.params) {
@@ -128,7 +98,9 @@
 	    var packageInfo = (data.get( data.find({kind: 'package'}) ) || []) [0];
 
 	    data.forEach(function(doclet) {
-	        summarize(doclet);
+	        doclet.signature = '';
+            doclet.attribs = '';
+
 	        if (doclet.kind === 'function' || doclet.kind === 'class') {
 	            addSignatureParams(doclet);
 	            addSignatureReturns(doclet);
@@ -157,7 +129,7 @@
 	        }
 	    });
 
-	    data.orderBy(['longname', 'kind', 'version', 'since']);
+	    data.orderBy(['longname', 'version', 'since']);
 
         // kinds of containers
         var globals = data.get( data.find({kind: ['property', 'function'], memberof: {isUndefined: true}}) ),
@@ -180,38 +152,70 @@
             fs.copyFile(fileName, toDir);
         });
 
-        // containers
-        //generate('Globals', globals, 'globals.html');
-        //generate('Modules', modules, 'modules.html');
-        //generate('Classes', classes, 'classes.html');
-        //generate('Namespaces', namespaces, 'namespaces.html');
+        function linkto(longname, linktext) {
+            var url = longnameToUrl[longname];
+            return url? '<a href="'+url+'">'+linktext+'</a>' : (linktext || longname);
+        }
 
         var urlToLongname = {},
             longnameToUrl = {};
 
-        var classes = data.get(data.find({kind: 'class'}));
-        for (var i = 0, len = classes.length; i < len; i++) {
-            var longname = classes[i].longname,
-                urlSafe = longname.replace(/[^$a-z0-9._-]/gi, '_');
+        data.forEach(function(doclet) {
+            var longname = doclet.longname,
+                urlSafe = longname.replace(/[^$a-z0-9._-]/gi, '_'), // TODO handle name collisions
+                url = urlSafe + '.html';
 
             // bidirectional lookups: url <=> longname
             urlToLongname[urlSafe]  = longname;
-            longnameToUrl[longname] = urlSafe;
+            longnameToUrl[longname] = url;
+        });
+
+        var nav = '',
+            seen = {};
+
+        var moduleNames = data.get( data.find({kind: 'module'}) );
+        if (moduleNames.length) {
+            nav = nav + '<h3>Modules</h3><ul>';
+            moduleNames.forEach(function(m) {
+                if (!seen[m.longname]) nav += '<li>'+linkto(m.longname, m.name)+'</li>';
+                seen[m.longname] = true;
+            });
+
+             nav = nav + '</ul>';
+        }
+        var classNames = data.get( data.find({kind: 'class'}) );
+        if (classNames.length) {
+            nav = nav + '<h3>Classes</h3><ul>';
+            classNames.forEach(function(c) {
+                if (!seen[c.longname]) nav += '<li>'+linkto(c.longname, c.name)+'</li>';
+                seen[c.longname] = true;
+            });
+
+             nav = nav + '</ul>';
         }
 
         for (var longname in longnameToUrl) {
             var classes = data.get( data.find({kind: 'class', longname: longname}) );
-            generate(classes[0].kind+': '+classes[0].name, classes, longnameToUrl[longname]+'.html');
+            if (classes.length) generate('Class: '+classes[0].name, classes, longnameToUrl[longname]);
+
+            var modules = data.get( data.find({kind: 'module', longname: longname}) );
+            if (modules.length) generate('Module: '+modules[0].name, modules, longnameToUrl[longname]);
+
+            var namespaces = data.get( data.find({kind: 'namespace', longname: longname}) );
+            if (namespaces.length) generate('Namespace: '+namespaces[0].name, namespaces, longnameToUrl[longname]);
+
         }
 
         function generate(title, docs, filename) {
             var data = {
                 title: title,
                 docs: docs,
+                nav: nav,
 
                 // helpers
                 render: render,
                 find: find,
+                linkto: linkto,
                 htmlsafe: htmlsafe
             };
 

templates/default/static/styles/jsdoc-default.css

@@ -3,7 +3,6 @@ body
 	font-family: "Lucida Grande", "Lucida Sans Unicode", "Lucida Sans", Verdana, Tahoma, sans-serif;
 	font-size: 13px;
 	color: #000;
-	background-color: #E2ECF0;
 }
 
 header
@@ -19,14 +18,64 @@ header
 	font-size: 18px;
 }
 
+#main {
+    float: left;
+    width: 100%;
+}
+
 section
 {
 	display: block;
-	margin: 14px 28px;
+
 	background-color: #fff;
 	padding: 12px 24px;
-	-moz-border-radius: 7px;
-    border-radius: 7px
+
+    margin-right: 240px;
+}
+
+nav
+{
+	display: block;
+
+	float: left;
+    margin-left: -230px;
+    margin-top: 53px;
+    width: 220px;
+    border-left: 1px solid #ddd;
+    padding-left: 9px;
+}
+
+nav ul {
+    padding:0;
+    margin:0;
+    list-style-type:none;
+}
+
+nav h3 {
+    margin-top: 12px;
+}
+
+nav li {
+    margin-top: 6px;
+}
+
+nav a {
+    color: #000;
+}
+
+nav a:visited {
+    color: #000;
+}
+
+nav a:active {
+    color: #000;
+}
+
+footer {
+    display: block;
+    padding: 6px;
+    margin-top: 12px;
+    font-style: italic;
 }
 
 h1
@@ -69,7 +118,7 @@ h5
 	font-size: 16px;
 	font-weight: bold;
 	letter-spacing: -0.03em;
-	margin: 6px 0 3px 0;
+	margin: 8px 0 3px -16px;
 }
 
 h6
@@ -88,10 +137,10 @@ h6
     color: #aaa;
 }
 
-/*.description {
-    font-family: Palatino, "Palatino Linotype", serif;
-	font-size: 14px;
-}*/
+.details dt { width:100px; float:left;}
+.details dd { margin-left: 100px; }
+
+.description { margin-left: -16px; }
 
 .code-caption
 {