jsdoc-parse

Jsdoc-annotated source code in, JSON format documentation out.

jsdoc-parse

Jsdoc-annotated source code in, JSON format documentation out.

Essentially, the output is the raw JSON output of jsdoc with a few extras:

  • Support for html input files (see --html option).
  • Support for new tags in the input javascript
    • @category <string>: Useful for grouping identifiers by category.
    • @done: Used to mark @todo items 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 for jQuery instances), _ (underscore) etc.
    • @chainable: Set to mark a method as chainable (has a return value of this).
  • Some new fields:
    • id: a unique identifier (the jsdoc longname field is not guaranteed unique)
    • isExported: set to true on the identifier which is exported from a module.
    • todoList: A list.
    • typicalname
    • category
    • order: The sort position of the identifier in the source file. Useful for use in --sort-by expressions.
  • A separate constructor record. In jsdoc, the class and constructor information are contained within the same record. In jsdoc-parse, the constructor information is separated from the class into a record with kind "constructor".
$ 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
  }
]

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(victimcrazyHair){}

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
  }
]

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
  }
]

Tested on Mac OSX, Linux, Windows 8.1 and Windows XP.

Useful for quick access to the data..

$ npm install -g jsdoc-parse
$ jsdoc-parse --help
 
  jsdoc-parse
  Jsdoc-annotated source code in, JSON format documentation out.
 
  Usage
  $ jsdoc-parse <files>
  $ cat <files> | jsdoc-parse
 
  --private              Include identifiers marked @private in the output
  --stats                Print a few stats about the doclets parsed
  --html                 Enable experimental parsing of .html files
  --src <array>          A list of javascript source files or glob expressions
  -s, --sort-by <array>  Sort by one of more fields, e.g. `--sort-by kind category`. Defaults to 'scope kind'.
  -h, --help

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.

For use within your node.js app.

$ npm install jsdoc-parse --save

##API Reference Exports a single function to parse jsdoc data.

Example

var parse = require("jsdoc-parse");

parse(src, options) ⇒ Transform

Documented javascript source in, documentation JSON out.

Kind: Exported function
Todo

  • [ ] split into two separate methods

Params

  • src string | Array.<string> - source file(s) to parse
  • options object - options
    • [stats =false] boolean - Return stats about the doclets parsed
    • [private =false] boolean - include @private members in the output
    • [html =false] boolean - if set, you can parse jsdoc from html files
    • [sort-by =[ "scope", "category", "kind", "order" ]] Array - sort the output

Example

parse("lib/jsdoc-parse.js").pipe(process.stdout);

© 2015 Lloyd Brookes <75pound@gmail.com>. Documented by jsdoc-to-markdown.