Package Exports

jsdoc-parse

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (jsdoc-parse) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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 --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).

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 --save

API Reference

Exports a single function to parse jsdoc data.

Example

var parse = require("jsdoc-parse")

jsdoc-parse
- jsdocParse([options]) ⇒ TransformStream ⏏
  - ~ParseOptions
    - .src : string | Array.<string>
    - .private : boolean
    - .stats : boolean
    - .html : boolean
    - .conf : boolean
    - .sort-by : array

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>
- .private : boolean
- .stats : boolean
- .html : boolean
- .conf : boolean
- .sort-by : array

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").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"]

jsdoc-parse

Package Exports

Readme

jsdoc-parse

Synopsis

Simple example

Longer example

HTML input example

Install and use

As a command-line tool

As a library

API Reference

jsdocParse([options]) ⇒ TransformStream ⏏

jsdocParse~ParseOptions

parseOptions.src : string | Array.<string>

parseOptions.private : boolean

parseOptions.stats : boolean

parseOptions.html : boolean

parseOptions.conf : boolean

parseOptions.sort-by : array

jsdocParse([options]) ⇒ `TransformStream` ⏏

parseOptions.src : `string` | `Array.<string>`

parseOptions.private : `boolean`

parseOptions.stats : `boolean`

parseOptions.html : `boolean`

parseOptions.conf : `boolean`

parseOptions.sort-by : `array`