Skip to content
Browse files

dont write `param` for function params in generated documentation

  • Loading branch information...
1 parent cdd5e9c commit ae2b6f2a13fe7aba07ada52290c457189e162299 @ttezel committed Nov 16, 2012
Showing with 36 additions and 50 deletions.
  1. +6 −18 api.html
  2. +12 −12 api.md
  3. +3 −9 examples/no-config/readme.html
  4. +6 −6 examples/no-config/readme.md
  5. +1 −1 lib/generateDocs.js
  6. +7 −3 lib/renderDocs.js
  7. +1 −1 templates/default.md
View
24 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>
View
24 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>
View
12 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>
View
12 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>
View
2 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
View
10 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
View
2 templates/default.md
@@ -20,7 +20,7 @@
{{type}} {{#name}}`{{name}}`{{/name}}: {{#types}}**{{.}}** {{/types}} {{description}}
{{/tags}}
-###Description
+
{{{description.full}}}
{{/isPrivate}}

0 comments on commit ae2b6f2

Please sign in to comment.
Something went wrong with that request. Please try again.