jsdoc-parse
Jsdoc-annotated source code in, JSON format documentation out.
jsdoc-parse extends jsdoc with a few features:
- Support for html input files (see
--htmloption). - Support for new tags in the input javascript
-
@category <string>: Useful for grouping identifiers by category. -
@done: Used to mark@todoitems as complete. -
@typicalname: If set on a class, namespace or module, child members will documented using this typical name as the parent name. Real-world typical name examples are$(the typical name forjQueryinstances),_(underscore) etc. -
@chainable: Set to mark a method as chainable (has a return value ofthis).
-
Synopsis
Simple example
$ echo "/** a wonderful global */ var majestic = true;" | jsdoc-parse
[
{
"id": "majestic",
"longname": "majestic",
"name": "majestic",
"scope": "global",
"kind": "member",
"description": "a wonderful global",
"order": 0
}
]
Longer example
This input javascript:
/**
Pump an idiot full of volts. Returns a promise they will slump.
@deprecated
@param {object | array} - the victim(s) to fry
@param [crazyHair=true] {boolean} - optional spikey hair effect
@return {external:Promise}
@resolve {Slump}
*/
function taze(victim, crazyHair){}returns this JSON:
$ jsdoc-parse example/function.js
[
{
"id": "taze",
"longname": "taze",
"name": "taze",
"scope": "global",
"kind": "function",
"description": "Pump an idiot full of volts. Returns a promise they will slump.",
"params": [
{
"type": {
"names": [
"object",
"array"
]
},
"description": "the victim(s) to fry",
"name": "victim"
},
{
"type": {
"names": [
"boolean"
]
},
"optional": true,
"defaultvalue": true,
"description": "optional spikey hair effect",
"name": "crazyHair"
}
],
"returns": [
{
"type": {
"names": [
"external:Promise"
]
}
}
],
"deprecated": true,
"customTags": [
{
"tag": "resolve",
"value": "{Slump}"
}
],
"order": 0
}
]HTML input example
This input HTML:
<!DOCTYPE html>
<html>
<head>
<script>
/**
something in the head
@type {number}
*/
var headGlobal = 1;
</script>
</head>
<body class="main">
<script>
/**
body global
@type {string}
@default
*/
var bodyGlobal = "one";
</script>
</body>
</html>produces this JSON output:
$ jsdoc-parse example/doc.html --html
[
{
"id": "headGlobal",
"longname": "headGlobal",
"name": "headGlobal",
"scope": "global",
"kind": "member",
"description": "something in the head",
"type": {
"names": [
"number"
]
},
"order": 0
},
{
"id": "bodyGlobal",
"longname": "bodyGlobal",
"name": "bodyGlobal",
"scope": "global",
"kind": "member",
"description": "body global",
"type": {
"names": [
"string"
]
},
"defaultvalue": "one",
"order": 1
}
]Install and use
As a command-line tool
Useful for quick access to the data..
jsdoc-parse
Jsdoc-annotated source code in, JSON format documentation out.
Synopsis
$ jsdoc-parse [-PH] [--sort-by fields] [--conf file] [--src file ...]
$ jsdoc-parse --help
$ jsdoc-parse --stats
Options
-f, --src file ... A list of javascript source files (or glob expressions) to parse for
documentation. If this option is not set jsdoc-parse will wait for source
code on stdin (i.e. `cat *.js | jsdoc-parse [options]`).
-P, --private Include identifiers marked @private in the output
-H, --html Enable experimental parsing of .html files
--conf file Path to a jsdoc configuration file, passed directly to `jsdoc -c`.
-s, --sort-by property ... Sort by one of more properties, e.g. `--sort-by kind category`. Defaults to
`[ "scope", "category", "kind", "order" ]`. Pass the special value `none` to
remove the default sort order.
--stats Print a few stats about the doclets parsed
-h, --help Display this usage.
Usage form 2 warning: When piping input into jsdoc-parse it will intepret the whole of what is piped in as a single file, so take care not to pipe in input containing multipe @modules as this is illegal in jsdoc (see here):
The @module tag marks the current file as being its own module. All symbols in the file are assumed to be members of the module unless documented otherwise.
As a library
For use within your node.js app.
$ npm install jsdoc-parse --saveAPI Reference
Exports a single function to parse jsdoc data.
Example
var parse = require("jsdoc-parse")
jsdocParse([options]) ⇒ TransformStream ⏏
Documented javascript source in, documentation JSON out.
Kind: Exported function
Params
- [options]
ParseOptions- parse options
Example
parse({ src:"lib/jsdoc-parse.js" }).pipe(process.stdout)jsdocParse~ParseOptions
All options for jsdoc-parse, including defaults
Kind: inner class of jsdocParse
parseOptions.src : string | Array.<string>
A list of javascript source files (or glob expressions) to parse for documentation. If this option is not set jsdoc-parse will wait for source code on stdin (i.e. cat *.js | jsdoc-parse <options>).
Kind: instance property of ParseOptions
Example
var parse = require("jsdoc-parse")
var fs = require("fs")
// either supply one or more file names
parse({ src: "example.js" }).pipe(process.stdout)
// or pipe in source code
fs.createReadStream("example.js").pipe(parse()).pipe(process.stdout)
parseOptions.private : boolean
Include identifier documentation marked as @private in the output
Kind: instance property of ParseOptions
Default: false
parseOptions.stats : boolean
Print a few stats about the doclets parsed
Kind: instance property of ParseOptions
parseOptions.html : boolean
Enable experimental parsing of .html files.
Kind: instance property of ParseOptions
Default: false
parseOptions.conf : boolean
Path to a jsdoc configuration file, passed directly to jsdoc -c.
Kind: instance property of ParseOptions
Default:
parseOptions.sort-by : array
Sort by one of more fields, e.g. --sort-by kind category. Pass the special value none to remove the default sort order.
Kind: instance property of ParseOptions
Default: ["scope","category","kind","order"]
© 2015 Lloyd Brookes <75pound@gmail.com>. Documented by jsdoc-to-markdown.