@nmarks/jsdoc-parse
Jsdoc-annotated source code in, JSON format documentation out.
Last updated 4 years ago by nmarks .
MIT · Repository · Bugs · Original npm · Tarball · package.json
$ cnpm install @nmarks/jsdoc-parse 
SYNC missed versions from official npm registry.

view on npm npm module downloads Build Status Dependency Status js-standard-style Join the chat at https://gitter.im/jsdoc2md/jsdoc2md

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

jsdocParse([options]) ⇒ TransformStream

Documented javascript source in, documentation JSON out.

Kind: Exported function
Params

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.

Current Tags

  • 1.2.7                                ...           latest (4 years ago)

1 Versions

  • 1.2.7                                ...           4 years ago
Maintainers (1)
Downloads
Today 0
This Week 0
This Month 0
Last Day 0
Last Week 0
Last Month 1
Dependencies (12)
Dev Dependencies (3)
Dependents (0)
None

Copyright 2014 - 2016 © taobao.org |