sutoiku / jsdox

simplified jsdoc 3

jsdox

jsdox is a simple jsdoc 3 generator. It pulls documentation tags based on a subset of jsdoc 3 from your javascript files and generates markdown files.

Relies on the JSDoc3 parser to get the full AST including comments.

CLI Options

Usage: jsdox [options] <file | directory>

--config <file> (alias -c): Configuration JSON file.

--All (alias -A): Generates documentation for all available elements including internal methods.

--debug (alias -d): Prints debugging information to the console.

--help (alias -H): Prints help and quits.

--version (alias -v): Prints the current version and quits.

--output <dir> (alias -o): Output directory. Default value is output.

--templateDir <dir> (alias -t): Template directory to use instead of built-in ones.

--index <name> (alias -i): Generates an index with the documentation. An optional file name can be provided as an argument. Default value is index.

--index-sort <type>: Defines how to sort the index. Options are: standard (sorted by name), namespace (sorted by package/module and name), and none (not sorted). Default value is standard.

--recursive (alias -r): Generates documentation in all subdirectories of the source folder.

--respect-recursive (alias --rr): Generate subdirectories and copy the original organization of the sources.

Resources

• jsdox Documentation
• Github repo
• Changelog
• Issue tracker
• Contribute by reading the guidelines and creating pull requests!
• Run the test suite using npm test

Related projects

• grunt-jsdox A grunt task to run jsdox on your project

Author and contributors

• Pascal Belloncle (psq, Original author)
• Sam Blowes (blowsie)
• Todd Henderson (thenderson21)
• Nic Jansma (nicjansma)
• Joel Kemp (mrjoelkemp)
• Ron Korving (ronkorving)
• Mike MacMillan (mmacmillan)
• Michael Martin-Smucker (mlms13)
• Akeem McLennon (bluelaguna)
• Gabor Sar (gaborsar)
• Marc Trudel (stelcheck)
• Anselm Stordeur (anselmstordeur)
• Vladimir de Turckheim (vdeturckheim)

License

jsdox.js is freely distributable under the terms of the MIT license.

Copyright (c) 2012-2016 Sutoiku

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

jsdox's Issues

npm install [email protected] is failing

npm ERR! fetch failed https://registry.npmjs.org/jsdox/-/jsdox-0.2.3.tgz
npm ERR! Error: 404 Not Found
npm ERR! at WriteStream. (/usr/local/Cellar/node/0.10.24/lib/node_modules/npm/lib/utils/fetch.js:57:12)
npm ERR! at WriteStream.EventEmitter.emit (events.js:117:20)
npm ERR! at fs.js:1596:14
npm ERR! at /usr/local/Cellar/node/0.10.24/lib/node_modules/npm/node_modules/graceful-fs/graceful-fs.js:103:5
npm ERR! at Object.oncomplete (fs.js:107:15)
npm ERR! If you need help, you may report this entire log,
npm ERR! including the npm and node versions, at:
npm ERR! http://github.com/isaacs/npm/issues

Allow for the --parser option

Allows the user to specify a particular version of jsdoc to use with JSDox. This avoids JSDox dictating the jsdoc version and having to maintain the dependency.

jsdox myFile --parser=path/to/my/jsdoc

• If --parser is not set, then check stdinput
• If no parser is supplied, either default to jsdoc3 (dynamically npm install) or use an internal parser?

Installation error

Hi!

When i do "npm install -g jsdox", the following message is coming:

C:\Users\Christian\node.js\doc>npm install -g jsdox
npm http GET https://registry.npmjs.org/jsdox
npm http 304 https://registry.npmjs.org/jsdox
npm http GET https://registry.npmjs.org/optimist
npm ERR! not found: git
npm ERR!
npm ERR! Failed using git.
npm ERR! This is most likely not a problem with npm itself.
npm ERR! Please check if you have git installed and in your PATH.

npm ERR! System Windows_NT 6.1.7601
npm ERR! command "C:\\Program Files\\nodejs\\\\node.exe" "C:\\Program Files\\nod
ejs\\node_modules\\npm\\bin\\npm-cli.js" "install" "-g" "jsdox"
npm ERR! cwd C:\Users\Christian\node.js\doc
npm ERR! node -v v0.10.26
npm ERR! npm -v 1.4.3
npm ERR! code ENOGIT
npm http 304 https://registry.npmjs.org/optimist
npm ERR!
npm ERR! Additional logging details can be found in:
npm ERR!     C:\Users\Christian\node.js\doc\npm-debug.log
npm ERR! not ok code 0

The npm-debug.log file:

0 info it worked if it ends with ok
1 verbose cli [ 'C:\\Program Files\\nodejs\\\\node.exe',
1 verbose cli   'C:\\Program Files\\nodejs\\node_modules\\npm\\bin\\npm-cli.js',
1 verbose cli   'install',
1 verbose cli   '-g',
1 verbose cli   'jsdox' ]
2 info using [email protected]
3 info using [email protected]
4 verbose node symlink C:\Program Files\nodejs\\node.exe
5 verbose cache add [ 'jsdox', null ]
6 verbose cache add name=undefined spec="jsdox" args=["jsdox",null]
7 verbose parsed url { protocol: null,
7 verbose parsed url   slashes: null,
7 verbose parsed url   auth: null,
7 verbose parsed url   host: null,
7 verbose parsed url   port: null,
7 verbose parsed url   hostname: null,
7 verbose parsed url   hash: null,
7 verbose parsed url   search: null,
7 verbose parsed url   query: null,
7 verbose parsed url   pathname: 'jsdox',
7 verbose parsed url   path: 'jsdox',
7 verbose parsed url   href: 'jsdox' }
8 silly lockFile fc3e298a-jsdox jsdox
9 verbose lock jsdox C:\Users\Christian\AppData\Roaming\npm-cache\fc3e298a-jsdox.lock
10 silly lockFile fc3e298a-jsdox jsdox
11 silly lockFile fc3e298a-jsdox jsdox
12 verbose addNamed [ 'jsdox', '' ]
13 verbose addNamed [ null, '*' ]
14 silly lockFile 948d0fc1-jsdox jsdox@
15 verbose lock jsdox@ C:\Users\Christian\AppData\Roaming\npm-cache\948d0fc1-jsdox.lock
16 silly addNameRange { name: 'jsdox', range: '*', hasData: false }
17 verbose url raw jsdox
18 verbose url resolving [ 'https://registry.npmjs.org/', './jsdox' ]
19 verbose url resolved https://registry.npmjs.org/jsdox
20 info trying registry request attempt 1 at 14:19:14
21 verbose etag "91HWP3K6LF284A0UP33N5WCPT"
22 http GET https://registry.npmjs.org/jsdox
23 http 304 https://registry.npmjs.org/jsdox
24 silly registry.get cb [ 304,
24 silly registry.get   { date: 'Sun, 30 Mar 2014 12:19:17 GMT',
24 silly registry.get     server: 'Apache',
24 silly registry.get     via: '1.1 varnish',
24 silly registry.get     'last-modified': 'Sun, 30 Mar 2014 12:19:17 GMT',
24 silly registry.get     'cache-control': 'max-age=1',
24 silly registry.get     etag: '"91HWP3K6LF284A0UP33N5WCPT"',
24 silly registry.get     'x-served-by': 'cache-fra1229-FRA',
24 silly registry.get     'x-cache': 'MISS',
24 silly registry.get     'x-cache-hits': '0',
24 silly registry.get     'x-timer': 'S1396181957.686727047,VS0,VE271',
24 silly registry.get     vary: 'Accept',
24 silly registry.get     'content-length': '0',
24 silly registry.get     'keep-alive': 'timeout=10, max=50',
24 silly registry.get     connection: 'Keep-Alive' } ]
25 verbose etag jsdox from cache
26 silly addNameRange number 2 { name: 'jsdox', range: '*', hasData: true }
27 silly addNameRange versions [ 'jsdox',
27 silly addNameRange   [ '0.1.0', '0.2.0', '0.2.1', '0.2.2', '0.2.4', '0.2.5', '0.2.6' ] ]
28 verbose addNamed [ 'jsdox', '0.2.6' ]
29 verbose addNamed [ '0.2.6', '0.2.6' ]
30 silly lockFile 7a16e6ea-jsdox-0-2-6 [email protected]
31 verbose lock [email protected] C:\Users\Christian\AppData\Roaming\npm-cache\7a16e6ea-jsdox-0-2-6.lock
32 silly lockFile 7a16e6ea-jsdox-0-2-6 [email protected]
33 silly lockFile 7a16e6ea-jsdox-0-2-6 [email protected]
34 silly lockFile 948d0fc1-jsdox jsdox@
35 silly lockFile 948d0fc1-jsdox jsdox@
36 silly resolved [ { author: { name: 'Pascal Belloncle', url: 'http://jsdox.org' },
36 silly resolved     maintainers: [ [Object] ],
36 silly resolved     licenses: [ [Object] ],
36 silly resolved     name: 'jsdox',
36 silly resolved     description: 'Simple JSDoc 3 to Markdown generator',
36 silly resolved     version: '0.2.6',
36 silly resolved     repository: { type: 'git', url: 'git://github.com/sutoiku/jsdox.git' },
36 silly resolved     main: './jsdox.js',
36 silly resolved     files: [ 'bin/jsdox', 'jsdox.js', 'LICENSE', 'README.md' ],
36 silly resolved     preferGlobal: true,
36 silly resolved     bin: { jsdox: './bin/jsdox' },
36 silly resolved     dependencies:
36 silly resolved      { optimist: '~0.3.4',
36 silly resolved        'uglify-js': 'git+https://github.com/psq/UglifyJS.git#master' },
36 silly resolved     devDependencies: { mocha: '1.0.x', should: '0.6.x' },
36 silly resolved     optionalDependencies: {},
36 silly resolved     engines: { node: '>=0.8.4' },
36 silly resolved     homepage: 'http://jsdox.org',
36 silly resolved     bugs: { url: 'https://github.com/sutoiku/jsdox/issues' },
36 silly resolved     readme: '# jsdox.js\n\njsdox is a simple jsdoc 3 generator.  It pulls documentation tags based on a subset of [jsdoc 3](http://usejsdoc.org/) from your javascript files and generates [markdown](http://daringfireball.net/projects/markdown/) files.\n\nRelies on (for now) patched version of the UglifyJS parser to get the full AST including comments\n\n# Resources\n* [jsdox](http://jsdox.org) Documentation \n* Github [repo](https://github.com/sutoiku/jsdox)\n* Issue [tracker](https://github.com/sutoiku/jsdox/issues)\n* Contribute by creating [pull requests](https://github.com/sutoiku/jsdox/pulls)!\n\n# Related projects\n* [grunt-jsdox](https://github.com/mmacmillan/grunt-jsdox) A grunt task\n  to run jsdox on your project\n\n# Author and Maintainers\n* Pascal Belloncle (psq, Original author)\n* Nic Jansma (nicjansma)\n* Ron Korving (ronkorving)\n* Mike MacMillan (mmacmillan)\n* Marc Trudel (stelcheck)\n\n# License\n\njsdox.js is freely distributable under the terms of the MIT license.\n\nCopyright (c) 2012-2014 Sutoiku\n\nPermission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation\nfiles (the "Software"), to deal in the Software without restriction, including without limitation the rights to use,\ncopy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\n',
36 silly resolved     readmeFilename: 'README.md',
36 silly resolved     _id: '[email protected]',
36 silly resolved     _from: 'jsdox@' } ]
37 info install [email protected] into C:\Users\Christian\AppData\Roaming\npm
38 info installOne [email protected]
39 info C:\Users\Christian\AppData\Roaming\npm\node_modules\jsdox unbuild
40 verbose tar unpack C:\Users\Christian\AppData\Roaming\npm-cache\jsdox\0.2.6\package.tgz
41 silly lockFile a56dc4ec-a-Roaming-npm-node-modules-jsdox tar://C:\Users\Christian\AppData\Roaming\npm\node_modules\jsdox
42 verbose lock tar://C:\Users\Christian\AppData\Roaming\npm\node_modules\jsdox C:\Users\Christian\AppData\Roaming\npm-cache\a56dc4ec-a-Roaming-npm-node-modules-jsdox.lock
43 silly lockFile c162d2f4-pm-cache-jsdox-0-2-6-package-tgz tar://C:\Users\Christian\AppData\Roaming\npm-cache\jsdox\0.2.6\package.tgz
44 verbose lock tar://C:\Users\Christian\AppData\Roaming\npm-cache\jsdox\0.2.6\package.tgz C:\Users\Christian\AppData\Roaming\npm-cache\c162d2f4-pm-cache-jsdox-0-2-6-package-tgz.lock
45 silly gunzTarPerm modes [ '755', '644' ]
46 silly gunzTarPerm extractEntry package.json
47 silly gunzTarPerm modified mode [ 'package.json', 438, 420 ]
48 silly gunzTarPerm extractEntry README.md
49 silly gunzTarPerm modified mode [ 'README.md', 438, 420 ]
50 silly gunzTarPerm extractEntry LICENSE
51 silly gunzTarPerm modified mode [ 'LICENSE', 438, 420 ]
52 silly gunzTarPerm extractEntry jsdox.js
53 silly gunzTarPerm modified mode [ 'jsdox.js', 438, 420 ]
54 silly gunzTarPerm extractEntry bin/jsdox
55 silly gunzTarPerm modified mode [ 'bin/jsdox', 438, 420 ]
56 silly lockFile a56dc4ec-a-Roaming-npm-node-modules-jsdox tar://C:\Users\Christian\AppData\Roaming\npm\node_modules\jsdox
57 silly lockFile a56dc4ec-a-Roaming-npm-node-modules-jsdox tar://C:\Users\Christian\AppData\Roaming\npm\node_modules\jsdox
58 silly lockFile c162d2f4-pm-cache-jsdox-0-2-6-package-tgz tar://C:\Users\Christian\AppData\Roaming\npm-cache\jsdox\0.2.6\package.tgz
59 silly lockFile c162d2f4-pm-cache-jsdox-0-2-6-package-tgz tar://C:\Users\Christian\AppData\Roaming\npm-cache\jsdox\0.2.6\package.tgz
60 info preinstall [email protected]
61 verbose readDependencies using package.json deps
62 verbose readDependencies using package.json deps
63 verbose cache add [ 'optimist@~0.3.4', null ]
64 verbose cache add name=undefined spec="optimist@~0.3.4" args=["optimist@~0.3.4",null]
65 verbose parsed url { protocol: null,
65 verbose parsed url   slashes: null,
65 verbose parsed url   auth: null,
65 verbose parsed url   host: null,
65 verbose parsed url   port: null,
65 verbose parsed url   hostname: null,
65 verbose parsed url   hash: null,
65 verbose parsed url   search: null,
65 verbose parsed url   query: null,
65 verbose parsed url   pathname: 'optimist@~0.3.4',
65 verbose parsed url   path: 'optimist@~0.3.4',
65 verbose parsed url   href: 'optimist@~0.3.4' }
66 verbose cache add name="optimist" spec="~0.3.4" args=["optimist","~0.3.4"]
67 verbose parsed url { protocol: null,
67 verbose parsed url   slashes: null,
67 verbose parsed url   auth: null,
67 verbose parsed url   host: null,
67 verbose parsed url   port: null,
67 verbose parsed url   hostname: null,
67 verbose parsed url   hash: null,
67 verbose parsed url   search: null,
67 verbose parsed url   query: null,
67 verbose parsed url   pathname: '~0.3.4',
67 verbose parsed url   path: '~0.3.4',
67 verbose parsed url   href: '~0.3.4' }
68 verbose addNamed [ 'optimist', '~0.3.4' ]
69 verbose addNamed [ null, '>=0.3.4-0 <0.4.0-0' ]
70 silly lockFile 094c60bd-optimist-0-3-4 optimist@~0.3.4
71 verbose lock optimist@~0.3.4 C:\Users\Christian\AppData\Roaming\npm-cache\094c60bd-optimist-0-3-4.lock
72 verbose cache add [ 'uglify-js@git+https://github.com/psq/UglifyJS.git#master',
72 verbose cache add   null ]
73 verbose cache add name=undefined spec="uglify-js@git+https://github.com/psq/UglifyJS.git#master" args=["uglify-js@git+https://github.com/psq/UglifyJS.git#master",null]
74 verbose parsed url { protocol: null,
74 verbose parsed url   slashes: null,
74 verbose parsed url   auth: null,
74 verbose parsed url   host: null,
74 verbose parsed url   port: null,
74 verbose parsed url   hostname: null,
74 verbose parsed url   hash: '#master',
74 verbose parsed url   search: null,
74 verbose parsed url   query: null,
74 verbose parsed url   pathname: 'uglify-js@git+https://github.com/psq/UglifyJS.git',
74 verbose parsed url   path: 'uglify-js@git+https://github.com/psq/UglifyJS.git',
74 verbose parsed url   href: 'uglify-js@git+https://github.com/psq/UglifyJS.git#master' }
75 verbose cache add name="uglify-js" spec="git+https://github.com/psq/UglifyJS.git#master" args=["uglify-js","git+https://github.com/psq/UglifyJS.git#master"]
76 verbose parsed url { protocol: 'git+https:',
76 verbose parsed url   slashes: true,
76 verbose parsed url   auth: null,
76 verbose parsed url   host: 'github.com',
76 verbose parsed url   port: null,
76 verbose parsed url   hostname: 'github.com',
76 verbose parsed url   hash: '#master',
76 verbose parsed url   search: null,
76 verbose parsed url   query: null,
76 verbose parsed url   pathname: '/psq/UglifyJS.git',
76 verbose parsed url   path: '/psq/UglifyJS.git',
76 verbose parsed url   href: 'git+https://github.com/psq/UglifyJS.git#master' }
77 silly lockFile 28b85054-ttps-github-com-psq-UglifyJS-git https://github.com/psq/UglifyJS.git
78 verbose lock https://github.com/psq/UglifyJS.git C:\Users\Christian\AppData\Roaming\npm-cache\28b85054-ttps-github-com-psq-UglifyJS-git.lock
79 silly addNameRange { name: 'optimist', range: '>=0.3.4-0 <0.4.0-0', hasData: false }
80 verbose addRemoteGit [ 'https://github.com/psq/UglifyJS.git', 'master' ]
81 verbose url raw optimist
82 verbose url resolving [ 'https://registry.npmjs.org/', './optimist' ]
83 verbose url resolved https://registry.npmjs.org/optimist
84 info trying registry request attempt 1 at 14:19:15
85 verbose etag "PA5VDCV0WJ41Q8BVL784CXVC"
86 http GET https://registry.npmjs.org/optimist
87 silly lockFile 28b85054-ttps-github-com-psq-UglifyJS-git https://github.com/psq/UglifyJS.git
88 silly lockFile 28b85054-ttps-github-com-psq-UglifyJS-git https://github.com/psq/UglifyJS.git
89 verbose about to build C:\Users\Christian\AppData\Roaming\npm\node_modules\jsdox
90 info C:\Users\Christian\AppData\Roaming\npm\node_modules\jsdox unbuild
91 info preuninstall [email protected]
92 info uninstall [email protected]
93 verbose true,C:\Users\Christian\AppData\Roaming\npm\node_modules,C:\Users\Christian\AppData\Roaming\npm\node_modules unbuild [email protected]
94 verbose C:\Users\Christian\AppData\Roaming\npm,[object Object] binRoot
95 info postuninstall [email protected]
96 error not found: git
97 error Failed using git.
97 error This is most likely not a problem with npm itself.
97 error Please check if you have git installed and in your PATH.
98 error System Windows_NT 6.1.7601
99 error command "C:\\Program Files\\nodejs\\\\node.exe" "C:\\Program Files\\nodejs\\node_modules\\npm\\bin\\npm-cli.js" "install" "-g" "jsdox"
100 error cwd C:\Users\Christian\node.js\doc
101 error node -v v0.10.26
102 error npm -v 1.4.3
103 error code ENOGIT
104 verbose exit [ 1, true ]

Can someone help me? I have no idea...

Thanks!

Recursive command doesn't ignore non-JS files

When I run the jsdox command recursively on a directory, debug shows that it's processing .txt, .json, and other file types. When those file types are hit, jsdox bails out with an exception, which means I can't recursively generate documentation.

It should allow a file mask (I've not seen an example supporting this). The jsdox website claimed a recursive directory parse would only pick up .js files, but apparently that's untrue.

Fatal error: ENOENT, no such file or directory './templates/file.mustache'

Getting subj error when installing via npm.
It's because templates directory is not installed.
thx

Fails on --rr with empty grandparent folder.

We have the following folder structure:

lib/
    /factories/
        /controllers
            foobar.js
        /models
            barfoo.js

jsdox fails on this when it tries to create the controllers and models folders, because the factories folder does not contain any files so it never gets created.

Finish .travis.yml integration

@psq I don't have admin rights to the repo, so I can't finish the travis-ci integration. The .travis.yml file is already merged in. Can you finish setting it up so that we can have the suite run on every submitted pull request?

You should be able to visit https://travis-ci.org/, find the jsdox repo, then finish the configuration.

Generate table of contents

grunt-jsdox can generate a TOC of the files that make up an API, but within a file, you're left to manually navigating through headings. A per-file ToC would be great.

add ability to use an env variable for specifying template directory location

This way, you no longer need to specify the --templateDir option each time you invoke jsdox.

Use JSCS to enforce style guidelines

How to document object params with particular properties

I think I must be missing something here but I cannot figure out how to properly document object parameters (with specific properties). This is some documented code using jsdoc3:

/**
 * Transition the globe from its current position
 * to the new coordinates.
 *
 * @param  {Object} pos - the position
 * @param  {Float} pos.lat - latitude position
 * @param  {Float} pos.lon - longtitute position
 * @return  {this}
 */
api.center = function(pos) {
  target = calculate2dPosition(pos);
  return this;
}

Will output:

Globe.center(pos, pos.lat, pos.lon)

Transition the globe from its current position to the new coordinates.

Parameters
pos: Object, the position
pos.lat: Float, latitude position
pos.lon: Float, longtitute position
Returns: this

The first line is what I am not really happy about (this function only has a single parameter which is an object). After looking at the code it seems like something that is easily fixed by filtering the params before constructing the paramsString, but I am pretty sure that I am missing something obvious here.

No documentation generated for comments not

If you run jsdox on sodium.js no output is generated.

How to get parameters of Class Constructor

Is there any way to get the parameters or examples from the constructor of a class?

My jsdoc for the constructor looks as follow:

/**

• Constructor for components
• @Class AmenitiesList
• @memberof comp.model
• @param {object} options overwrite defaults
  */

@copyright, @license, etc. do not show unless @overview is defined

See title.

ECMA6 Support

So far ECMA6 documentations generated are pretty satisfactory, except for class that has constructor. In such case title of class will be generated twice, once for class and second time for constructor. It would be nice if we could support this in future.

Here is the class and output for such usecase:
https://github.com/ivanstan/frontend-framework/blob/master/core/Controller.js
https://github.com/ivanstan/frontend-framework/blob/master/module/example/assets/docs/Controller.md

Jsdox doesn't handle optional parameters

I use optional parameter syntax in my jsdoc like:

@param {String} [foo] - Does foo

which is explained at http://usejsdoc.org/tags-param.html#optional-parameters-and-default-values

Jsdox, however, doesn't seem to stylise these optional parameters. Am I missing something?

Can you suppress the Global title at the top of the page?

Wondering if there is a way to suppress the "Global" section at the top. I'm generating documentation for a single class and I think the global space is pretty well assumed.

NPM Mustache vulnerability

You should update the version.

def14nt@lizard:~/Desktop/~~REDACTED~~> !!
npm audit

                       === npm audit security report ===

┌──────────────────────────────────────────────────────────────────────────────┐
│                                Manual Review                                 │
│            Some vulnerabilities require your attention to resolve            │
│                                                                              │
│         Visit https://go.npm.me/audit-guide for additional guidance          │
└──────────────────────────────────────────────────────────────────────────────┘
┌───────────────┬──────────────────────────────────────────────────────────────┐
│ High          │ Cross-Site Scripting                                         │
├───────────────┼──────────────────────────────────────────────────────────────┤
│ Package       │ mustache                                                     │
├───────────────┼──────────────────────────────────────────────────────────────┤
│ Patched in    │ >=2.2.1                                                      │
├───────────────┼──────────────────────────────────────────────────────────────┤
│ Dependency of │ jsdox [dev]                                                  │
├───────────────┼──────────────────────────────────────────────────────────────┤
│ Path          │ jsdox > mustache                                             │
├───────────────┼──────────────────────────────────────────────────────────────┤
│ More info     │ https://nodesecurity.io/advisories/62                        │
└───────────────┴──────────────────────────────────────────────────────────────┘
found 1 high severity vulnerability in 2095 scanned packages

Change api signature

Currently:

jsdox.generateForDir(input, output, templateDir, done);

Should be:

jsdox({
  input: '', 
  ouput: '',
  done: function() {}
});

This will be a major version bump.

code blocks do not keep indentation

The following should produce a code block with an indented line

      /**
      * Do something
      * @method something
      * ```
      * require('something', function(something){
      *   something.create();
      * });
      * ```
      */

Instead, all the indentation is removed. This is obviously problematic if you are trying to give examples of how to implement the function you are documenting.

Feature request, add optional recursion for `generateForDir()`

Would be great to see a optional recursion for generateForDir().

Alternatively an example using the file module or similar.
https://github.com/mikeal/node-utils/tree/master/file

Templatize markdown markup

We currently have the markup for the markdown docs hardcoded (e.g., how many ### go into an heading).

It would be great for customization if the user could supply a template directory via the cli. The templates could be mustache templates. The template files might have to abide by a particular naming convention like:

• h1.mustache
• h2.mustache
• list-item.mustache
• toc.mustache (table of contents)
• ...

Example template:

h1.mustache

# {{value}} 

Thoughts?

---

Partially satisfied by #31, but needs to be user-configurable.

Extract loadConfigFile into its own module + tests

Test cases to remember:

• Make sure to cover the use of path.resolve to test that it works within jsdox and within an external dir

Use JSDoc parser instead of reparsing comments

This will allow JSDox to stay concerned with transforming the parsed code into Markdown. I'll likely submit a PR for this soon.

No API documentation for templateDir

API documentation still looks like this:

jsdox.generateForDir(input, output, done);

This doesn't account for the addition of templateDir as a 3rd parameter, which means that following the documentation now throws an error (because jsdox tries to call .replace() on the done function, assuming that it is actually a string representing templateDir.

Add change log

First shot included here: 1bcf600

If I missed something, misrepresented something, or mis-attributed, please comment here, or create a PR.

Will close in a few days.

Support markdown output for all JSDoc tags

• @abstract (synonyms: @virtual) This member must be implemented (or overridden) by the inheritor.
• @access Specify the access level of this member (private, public, or protected).
• @alias Treat a member as if it had a different name.
• @Augments (synonyms: @extends) This object adds onto a parent object.
• @author Identify the author of an item.
• @borrows This object uses something from another object.
• @callback Document a callback function.
• @Class (synonyms: @constructor) This function is intended to be called with the "new" keyword.
• @classdesc Use the following text to describe the entire class.
• @constant (synonyms: @const) Document an object as a constant.
• @constructs This function member will be the constructor for the previous class.
• @copyright Document some copyright information.
• @default (synonyms: @DefaultValue) Document the default value.
• @deprecated Document that this is no longer the preferred way.
• @description (synonyms: @desc) Describe a symbol.
• @enum Document a collection of related properties.
• @event Document an event.
• @example Provide an example of how to use a documented item.
• @exports Identify the member that is exported by a JavaScript module.
• @external (synonyms: @host) Document an external class/namespace/module.
• @file (synonyms: @fileoverview, @overview) Describe a file.
• @fires (synonyms: @emits) Describe the events this method may fire.
• @function (synonyms: @func, @method) Describe a function or method.
• @global Document a global object.
• @ignore [todo] Remove this from the final output.
• @inner Document an inner object.
• @instance Document an instance member.
• @kind What kind of symbol is this?
• @Lends Document properties on an object literal as if they belonged to a symbol with a given name.
• @license [todo] Document the software license that applies to this code.
• @link Inline tag - create a link.
• @member (synonyms: @var) Document a member.
• @memberof This symbol belongs to a parent symbol.
• @mixes This object mixes in all the members from another object.
• @mixin Document a mixin object.
• @module Document a JavaScript module.
• @name Document the name of an object.
• @namespace Document a namespace object.
• @param (synonyms: @arg, @argument) Document the parameter to a function.
• @private This symbol is meant to be private.
• @property (synonyms: @prop) Document a property of an object.
• @protected This member is meant to be protected.
• @public This symbol is meant to be public.
• @readonly This symbol is meant to be read-only.
• @requires This file requires a JavaScript module.
• @returns (synonyms: @return) Document the return value of a function.
• @see Refer to some other documentation for more information.
• @since When was this feature added?
• @static Document a static member.
• @summary A shorter version of the full description.
• @this What does the 'this' keyword refer to here?
• @throws (synonyms: @exception) Describe what errors could be thrown.
• @todo Document tasks to be completed.
• @tutorial Insert a link to an included tutorial file.
• @type Document the type of an object.
• @typedef Document a custom type.
• @variation Distinguish different objects with the same name.
• @version Documents the version number of an item.

standard markdown

somewhat of a long term thing. There is a new (not that new) initiative to standardize markdown (http://standardmarkdown.com). So we should keep an eye on it, and check whether we generate something that meets the recommended markdown.

could take the form of an additional test to run against sample_output content.

let's see it it gets some adoption first.

Use cases for jsdox?

From @boneskull:

@psq I'm not really understanding the use case of jsdox against anything but very small codebases. If you have one file, you can generate a README.md from it (sort of; the file won't be named README.md and it won't go where you want, but that's another open issue). If you have multiple files, you get a directory (or directory hierarchy) full of Markdown files.

Is the user to browse them individually? They don't make a web site. They can't be used with Jekyll because they have no Front Matter. You could potentially create an entire GitHub wiki out of the non-hierarchical files (using -r; not -rr), but a wiki is not really suitable for API documentation. Does some other converter consume them and turn them into a PDF?

I've only used jsdox for a very small module or two b/c of its limitations. If it generated a Jekyll site (and had more tag support, of course), then it's a viable alternative to jsdoc itself.

Allow for the --templateDir option

Used for user-supplied tweaking of the generated JSDox output. If a user is unhappy with the default look and feel, this is a way around it.

Example usage:

jsdox myFile --templateDir=path/to/my/mustache/templates

Replace -rr with just -r?

@vdeturckheim What's the difference between --recursive and --respect-recursive? If I did jsdox -r inputDir -o outputDir I'd expect the output directory to have the same structure as the input directory.

Error: Unexpected end of input

I have a project that i Just started a couple of months ago, and set up jsdox. I just made some changes, and recently upgraded to Node 4.3.1 (not sure if that is causing the problem). But when I try to run jsdox now, I get:

Error generating docs for file featurama-client.js [SyntaxError: Unexpected end of input]
[SyntaxError: Unexpected end of input]
/Users/Rob/projects/featurama/node_modules/jsdox/jsdox.js:300
            throw err;
            ^

SyntaxError: Unexpected end of input
    at Object.parse (native)
    at jsdocParser._onComplete (/Users/Rob/projects/featurama/node_modules/jsdox/node_modules/jsdoc3-parser/index.js:37:19)
    at ChildProcess.exithandler (child_process.js:204:7)
    at emitTwo (events.js:87:13)
    at ChildProcess.emit (events.js:172:7)
    at maybeClose (internal/child_process.js:821:16)
    at Socket.<anonymous> (internal/child_process.js:319:11)
    at emitOne (events.js:77:13)
    at Socket.emit (events.js:169:7)
    at Pipe._onclose (net.js:469:12)

This is the file I'm running it on is this:

module.exports = function() {
  var list = {};

  /**
   *  Enable the indicated feature
   *
   *  @param    {String} featureName
   */
  function on(featureName) {
    list[featureName] = true;
  }

  /**
   *  Disable the indicated feature
   *
   *  @param    {String} featureName
   */
  function off(featureName) {
    list[featureName] = false;
  }

  /**
   *  Return the on/off status of the indicated feature
   *
   *  @param    {String} featureName
   */
  function enabled(featureName) {
    return list[featureName];
  }

  return {
    init: _buildList,
    on: on,
    off: off,
    enabled: enabled
  };
}();

It seems like deleting any line of code from this snippet (I've already ripped out some) fixes the problem. This, however, is not a very good solution. :)

I've traced it back to line 17 of jsdoc3-parser, and I've tried to play with the maxBuffer size, but have not had any luck.
execFile(cmd, ['-X', filename], { maxBuffer: 5120 * 1024 }, jsdocParser._onComplete.bind(null, cb));

@fires not supported

JSDoc documentation http://usejsdoc.org/tags-fires.html

jsdox --output doc index.js

32: Tag not supported: fires
33: Tag not supported: fires
65: Tag not supported: fires
66: Tag not supported: fires
140: Tag not supported: fires
141: Tag not supported: fires
163: Tag not supported: fires
184: Tag not supported: fires
185: Tag not supported: fires
217: Tag not supported: fires

Cheers and thanks for the neat tool!

Generated paths do not work when generated content is pushed to Git.

Love the generator, has a lot of promise, but...

I'm generating our api with the intent of using it as browsable content on our Git server (in our case GitLab). I have pointed to a templatesDir and that appears to work for customizing the appearance of a class, but for the life of me I cannot effect what is rendered in the contentsFile.
For the contentsFile, the generated paths are all wrong. Because I build this on a windows machine, it uses backslashes in the paths, which means it all fails when I upload it to GitLab. Users can see the contentsFile but all links within it, use backslashes not forward slashes so none of the links are valid.
I used string-replace to get round this but the paths start with a slash (/) and in order to get it to work correctly so all paths are relative to the contentFile, I need it to start with dot-slash (./).

Essentially, there needs to be a means of formatting the path so developers not fortunate enough to be allowed use anything other than windows in their company, have a chance at using this.

Enable Sourcegraph

I want to use Sourcegraph for jsdox code search, browsing, and usage examples. Can an admin enable Sourcegraph for this repository? Just go to https://sourcegraph.com/github.com/sutoiku/jsdox. (It should only take 30 seconds.)

Thank you!

New line with @param and @return tags

Hi there !

I'm currently using JSDox and it's a pretty nice module, thank you for your work :)
While commenting my functions/methods, I've noticed that JSDox seems not to support new lines in @param and @return descriptions. I've used new lines in order not to write lines longer than 72 characters, and during the documentation generation process, these descriptions are cut at the end of the first line (which is not the case with general functions / methods description by the way).
Have you an idea about where that can come from ?
Thanks in advance !

Support piped input via stdin

Allows for an alternative way to supply a parser by feeding an AST directly into JSDox as input.

jsdoc -X myfile | jsdox

specify input file + output file

Maybe related to #40 but regardless, I want to read path/to/foo.js and have it output into a file README.md.

Support for documenting methods of inner classes separately

The following results in the innerClass methods being shown in the inner and outer class documentation.

Inner class methods should only appear in the documentation for the inner class

/**
* @class OuterClass
*/
var exports = {
    /**
    * @method outerClassMethod
    */
    outerClassMethod: function(){
        /**
        * @class innerClass
        */
        return {
            /**
            * @method innerClassMethod
            */
            innerMethod: function(){}
        }
    }
}
return exports;

Edit: or implement @memberOf annotation.

Line numbers in markdown output

Have the line numbers point back to the source files. Assume github line number linking in the url?

Should we deprecate the use of a config file?

It's not documented anywhere and I'm not sure what the real benefit of supporting a configuration with cli options to specify the input and output.

cc @psq

@namespace not supported results in no tags?

Hi,

I just ran a quick test against abaaso and your project parsed everything, but lost all context. The result is a markdown file in the following format:

function()
description

All other details are lost.

Param descriptions show function description of no param description was defined

/**

• This is a description
  *
• Multi Line Description
  *
• @param foo
  */

The description for foo will be "Multi Line Description".

Contribution.md additions

1. Formally state that stylistic changes to internal mustache templates that don't introduce support for new tags will not be accepted in PRs. We should defer those contributions to the use of custom templates via the templateDir option.

Private methods aren't ignored in output

Unless an --All option is passed, methods tagged with @private shouldn't show up in the documentation, correct? They seem to still show up in my docs, and I think I've tracked the problem to this code in analyze.js

function isInternal(tag){
  return tag && ((tag.name && tag.name.lastIndexOf('_', 0) === 0) || tag.private);
}

As it turns out, tag.private doesn't exist, but tag.access === 'private' is there. I'll have a PR in a bit that should fix this.

Broken tags view

See screenshot, headings should be on seperate lines

Support of @example

Hi,
I try to generate API examples using the @example tag without success. It is not documented in the tags doc however it is in the sample_output/test.md and in the code (js + mustache).
I would like to know the status for this feature.

jsdox -v Version: 0.4.2
node --version v0.10.26

Unit tests for lib/analyze

gulp-jsdox

We could really use some help getting a gulp plugin together for jsdox.

I reserved the npm name: gulp-jsdox. Repo located at https://github.com/mrjoelkemp/gulp-jsdox.

is this being maintained?

I'm currently using jsdox and tinkering with it, so I would volunteer to take over this module if it is not being maintained. There is at least one PR that's been sitting for some time, so I was curious.

thanks
Chris