dont write param for function params in generated documentation

api.html

@@ -187,9 +187,7 @@ <h2 id="filelibbuildconfigjs">File: lib/buildConfig.js</h2>
 
 <h3 id="functionmoduleexportscb">function module.exports(cb)</h3>
 
-<p>param <code>cb</code>: <strong>Function</strong>   completion callback. Signature: function (err)</p>
-
-<h3 id="description">Description</h3>
+<p><code>cb</code>: <strong>Function</strong>   completion callback. Signature: function (err)</p>
 
 <p>Build self.config, call <code>cb</code> on completion.</p>
 
@@ -205,46 +203,36 @@ <h2 id="filelibgeneratedocsjs">File: lib/generateDocs.js</h2>
 
 <h3 id="functionmoduleexportscb">function module.exports(cb)</h3>
 
-<p>param <code>cb</code>: <strong>function</strong>   completion callback. Function (err)</p>
-
-<h3 id="description">Description</h3>
+<p><code>cb</code>: <strong>function</strong>   completion callback. Signature: function (err)</p>
 
 <p>Traverse down the root and run .renderDoc() as files are discovered.</p>
 
 <h2 id="filelibinitializedocjs">File: lib/initializeDoc.js</h2>
 
 <h3 id="functionmoduleexportscb">function module.exports(cb)</h3>
 
-<p>param <code>cb</code>: <strong>Function</strong>   completion callback. Signature: function (err)</p>
-
-<h3 id="description">Description</h3>
+<p><code>cb</code>: <strong>Function</strong>   completion callback. Signature: function (err)</p>
 
 <p>initialize html doc (write css) &amp; delete markdown file (if exists)</p>
 
 <h2 id="filelibrenderdocsjs">File: lib/renderDocs.js</h2>
 
 <h3 id="functionmoduleexportsfiles">function module.exports(files)</h3>
 
-<p>param <code>files</code>: <strong>array</strong>   array of absolute paths of files to document</p>
+<p><code>files</code>: <strong>array</strong>   array of absolute paths of files to document</p>
 
-<h3 id="description">Description</h3>
-
-<p>Run <code>dox</code> on @file, render markdown &amp; html, then write to doc files</p>
+<p>Run dox on <code>files</code>, render markdown &amp; html, then write to doc files</p>
 
 <h2 id="filelibwritemejs">File: lib/writeme.js</h2>
 
 <h3 id="functionwritemeroot">function Writeme(root)</h3>
 
-<p>param <code>root</code>: <strong>String</strong>   absolute path to the directory (or file) to be documented</p>
-
-<h3 id="description">Description</h3>
+<p><code>root</code>: <strong>String</strong>   absolute path to the directory (or file) to be documented</p>
 
 <p>Writeme class</p>
 
 <p>Sets up writeme configuration, and kicks off the doc generation</p>
 
 <h3 id="writemeprototype">Writeme.prototype</h3>
 
-<h3 id="description">Description</h3>
-
 <p>Attach prototype methods from lib directory</p>

api.md

@@ -3,9 +3,9 @@
 ##File: lib/buildConfig.js
 
 ###function module.exports(cb)
-param `cb`: **Function**   completion callback. Signature: function (err)
+ `cb`: **Function**   completion callback. Signature: function (err)
+
 
-###Description
 <p>Build self.config, call <code>cb</code> on completion.</p>
 
 <p>Default config <code>include</code> array includes all .js files found in root, excluding the<br />default ignore list and files/directories prefixed with '.'</p>
@@ -21,45 +21,45 @@ param `cb`: **Function**   completion callback. Signature: function (err)
 ##File: lib/generateDocs.js
 
 ###function module.exports(cb)
-param `cb`: **function**   completion callback. Function (err)
+ `cb`: **function**   completion callback. Signature: function (err)
+
 
-###Description
 <p>Traverse down the root and run .renderDoc() as files are discovered.</p>
 
 
 
 ##File: lib/initializeDoc.js
 
 ###function module.exports(cb)
-param `cb`: **Function**   completion callback. Signature: function (err)
+ `cb`: **Function**   completion callback. Signature: function (err)
+
 
-###Description
 <p>initialize html doc (write css) &amp; delete markdown file (if exists)</p>
 
 
 
 ##File: lib/renderDocs.js
 
 ###function module.exports(files)
-param `files`: **array**   array of absolute paths of files to document
+ `files`: **array**   array of absolute paths of files to document
 
-###Description
-<p>Run <code>dox</code> on @file, render markdown &amp; html, then write to doc files</p>
+
+<p>Run dox on <code>files</code>, render markdown &amp; html, then write to doc files</p>
 
 
 
 ##File: lib/writeme.js
 
 ###function Writeme(root)
-param `root`: **String**   absolute path to the directory (or file) to be documented
+ `root`: **String**   absolute path to the directory (or file) to be documented
+
 
-###Description
 <p>Writeme class</p>
 
 <p>Sets up writeme configuration, and kicks off the doc generation</p>
 
 ###Writeme.prototype
-###Description
+
 <p>Attach prototype methods from lib directory</p>
 
 

examples/no-config/readme.html

@@ -185,26 +185,20 @@ <h1 id="noconfig">no-config</h1>
 
 <h2 id="fileclassjs">File: class.js</h2>
 
-<h3 id="description">Description</h3>
-
 <p>Testing code for writeme</p>
 
 <h3 id="functionclassfoobar">function Class(foo,bar)</h3>
 
-<p>param <code>foo</code>: <strong>string</strong>   foo description</p>
-
-<p>param <code>bar</code>: <strong>string</strong>   bar description</p>
+<p><code>foo</code>: <strong>string</strong>   foo description</p>
 
-<h3 id="description">Description</h3>
+<p><code>bar</code>: <strong>string</strong>   bar description</p>
 
 <p>Class description</p>
 
 <h3 id="functionclasspublicmethodbaz">function Class.publicMethod(baz)</h3>
 
-<p>param <code>baz</code>: <strong>string</strong>   baz description</p>
+<p><code>baz</code>: <strong>string</strong>   baz description</p>
 
 <p>return : <strong>boolean</strong>   bool description</p>
 
-<h3 id="description">Description</h3>
-
 <p>publicMethod description</p>

examples/no-config/readme.md

@@ -2,23 +2,23 @@
 
 ##File: class.js
 
-###Description
+
 <p>Testing code for writeme</p>
 
 ###function Class(foo,bar)
-param `foo`: **string**   foo description
+ `foo`: **string**   foo description
+
+ `bar`: **string**   bar description
 
-param `bar`: **string**   bar description
 
-###Description
 <p>Class description</p>
 
 ###function Class.publicMethod(baz)
-param `baz`: **string**   baz description
+ `baz`: **string**   baz description
 
 return : **boolean**   bool description
 
-###Description
+
 <p>publicMethod description</p>
 
 

lib/generateDocs.js

@@ -6,7 +6,7 @@ var fs = require('fs')
 /**
  * Traverse down the root and run .renderDoc() as files are discovered.
  *
- * @param {function} cb   completion callback. Function (err) 
+ * @param {function} cb   completion callback. Signature: function (err) 
  */
 module.exports = function generateDocs (cb) {
   var self = this

lib/renderDocs.js

@@ -7,7 +7,7 @@ var cp = require('child_process')
   , Showdown = require('showdown')
 
 /**
- * Run `dox` on @file, render markdown & html, then write to doc files
+ * Run dox on `files`, render markdown & html, then write to doc files
  *
  * @param  {array} files  array of absolute paths of files to document
  */
@@ -55,7 +55,9 @@ module.exports = function renderDocs (files) {
           throw error
         }
 
-        //generate function signature for any doc block that's a function
+        //augment dox's output.
+        // - generate function signature for any doc block that's a function
+        // - if a tag type is `param`, set the `type` field to null for better rendering
         var doxOut = doxOutput.map(function (docBlock) {
           //if this doc block is a function, write its signature
           if (!docBlock.ctx)
@@ -67,8 +69,10 @@ module.exports = function renderDocs (files) {
             var params = []
 
             docBlock.tags.forEach(function (tag) {
-              if (tag.type === 'param')
+              if (tag.type === 'param') {
                 params.push(tag.name)
+                tag.type = null
+              }
             })
             var paramString = params.join(',')
             var name = null

templates/default.md

@@ -20,7 +20,7 @@
 {{type}} {{#name}}`{{name}}`{{/name}}: {{#types}}**{{.}}** {{/types}}  {{description}}
 
 {{/tags}}
-###Description
+
 {{{description.full}}}
 {{/isPrivate}}