documentation-lite
Extract JSDoc documentation from ES5/ES6 files into a JSON output structure.
This is a wrapper around the excellent documentation.js which simplifies the returned JSON to make it easier to use for further processing.
At present it does not resolve external dependencies, and is designed for processing one file at a time.
Features:
- Works with both code strings and files.
- Works with constants, classes, static methods and generator methods.
- Uses Markdown formatting where needed (e.g. for inline code)
- Can optionally attach original source code to each tree node.
Example
/** * Aaah, a Jedi weapon! * * Use this wisely, or not, it's upto you really. */ /** * Destroy all possibilities of this weapon. */ static { console; } /** * This is the constructor. * * Just in case you don't get that let me add the `constructor` tag too! * @constructor */ { super'Will you be my friend?'; thisdukeNukemQuote = 'Come get some'; } /** * Strike an opponent. * * Maul them down, completely. * * @return */ { console; this; return success: true ; } /** * Strike an opponent asynchronously. * * @see strike */ * { return this; } /** * @override * @see Weapon#getType */ { return 'light sabre'; }
Will output:
"classes": "name": "LightSabre" "tags": {} "description": "Aaah, a Jedi weapon!" "Use this wisely, or not, it's upto you really." "parents": "name": "Weapon" "instance": "constructor": "name": "constructor" "tags": "_constructor": "description": null "description": "This is the constructor." "Just in case you don't get that let me add the `constructor` tag too!" "params": "returns": "throws": "methods": "strike": "name": "strike" "tags": "return": "description": "will have `success: true` set." "type": "name": "Object" "description": "Strike an opponent." "Maul them down, completely." "params": "name": "opponent" "description": "type": {} "returns": "description": "will have `success: true` set." "type": "name": "Object" "throws": "strikeAsync": "name": "strikeAsync" "tags": "see": "description": "strike" "description": "Strike an opponent asynchronously." "params": "name": "opponent" "description": "type": {} "returns": "throws": "properties": "a": "name": "a" "getter": "name": "a" "tags": "override": "description": null "see": "description": "Weapon#getType" "description": "params": "returns": "throws": "static": "methods": "name": "destroyAll" "tags": {} "description": "Destroy all possibilities of this weapon." "params": "returns": "throws": "constructor": "name": "constructor" "tags": "_constructor": "description": null "description": "This is the constructor." "Just in case you don't get that let me add the `constructor` tag too!" "params": "returns": "throws":
For more examples see the test/data folder.
Installation
npm install documentation-lite
Usage
Import the module:
const docLite = ;
There are two API methods, both of which are asynchronous and return Promises, and also accept callbacks in case that's how you'd rather code:
** * Extract documentation from given string of code * * @param String codeStr String of code to process * @param Object options Additional options * @param Boolean optionsincludeCode If set then each output node will include a `code` key containing the original relevant source code * @param Function cb Result callback in case you do not want to use Promises * @return Promise resolves to JSON structure */; /** * Extract documentation from given file. * * @param * @param * @param * @param * @return */;
Using with a Promise
Using processString()
with a Promise:
const code = `/** * A variable! * @type {String} */const DIR = __dirname;`; docLite ;
Will output:
"constants": "name": "DIR" "tags": "type": "description": null "type": "name": "String" "description": "A variable!" "type": "description": null "type": "name": "String"
Using with a callback
Using processFile()
with a callback:
docLite;
Attaching code to output JSON
Example input file:
/** * Output a message * @param */exports { console;}
Let's extract the docs:
docLite;
Will output:
"methods": "name": "print" "tags": ... "description": ... "params": ... "returns": "throws": "code": "exports.print = function(msg) {" " console.log(msg);" "}"
Contributors
Contributions welcome - see CONTRIBUTING.md
License
MIT - see LICENSE.md