quick post on how to easily generate documentation describing your JavaScript.
JSDoc - http://usejsdoc.org/
Advantages:
Disadvantages:
Gotchas:
On Windows:
Dependencies:
Java JDK should be in the PATH environment variable.
Download & Documentation:
http://usejsdoc.org/
Other tools:
I tried some other tools, but they were all poor quality (at least for JavaScript) or else hard to install:
Reference:
http://www.lsauer.com/2013/05/javascript-documentation-generator.html
http://stackoverflow.com/questions/1221413/what-tools-are-available-for-documenting-javascript
JsDoc tutorial:
http://www.2ality.com/2011/08/jsdoc-intro.html
JsDoc tags:
https://code.google.com/p/jsdoc-toolkit/wiki/TagReference
JSDoc - http://usejsdoc.org/
Advantages:
- used by jQuery
- easy to install
- easy to use
- seems able to handle complex JavaScript (where other tools could not!)
Disadvantages:
- you must add comments in a certain format, otherwise nothing appears in the generated documentation. However, the format of the comment is really simple:
Gotchas:
On Windows:
- you need to install in a location that has a space
- use the batch file: jsdocs.cmd
- instead of specifying everything on the command line, it is best to use a .conf file
- if you see this horrible exception, SOMETIMES it simply means 'file not found' - you need to check your command line arguments and check your conf file. BUT it also seems to be triggered by particular JavaScript files that JsDocs 3.3 cannot parse ?
- note: version 3.2 Release is more robust on Windows, as compared to 3.3
Dependencies:
Java JDK should be in the PATH environment variable.
Download & Documentation:
http://usejsdoc.org/
Other tools:
I tried some other tools, but they were all poor quality (at least for JavaScript) or else hard to install:
- JSDoc running on node.js - http://usejsdoc.org/
- could not get this to work on my system (Windows 8.1 if that matters ...)
- Natural Docs - http://www.naturaldocs.org/
- could not cope with any moderately sized JavaScript file, and failed with jQuery.
- almost all JavaScript projects use jQuery, so this is really a critical defect !
- docco - http://jashkenas.github.io/docco/
- easy to install and use
- BUT output is basically useless (at least for JavaScript)
Reference:
http://www.lsauer.com/2013/05/javascript-documentation-generator.html
http://stackoverflow.com/questions/1221413/what-tools-are-available-for-documenting-javascript
JsDoc tutorial:
http://www.2ality.com/2011/08/jsdoc-intro.html
JsDoc tags:
https://code.google.com/p/jsdoc-toolkit/wiki/TagReference
Comments
Post a Comment