JSPM – jsdoc-x@0.4.8

Package Exports

jsdoc-x

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-x) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

jsdoc-x

npm release license

Parser for outputting a customized Javascript object from documented code via JSDoc's explain (-X) command.

© 2016, Onur Yıldırım (@onury). MIT License.

Install via NPM:

npm install jsdoc-x

Usage:

var jsdocx = require('jsdoc-x');

`jsdocx.parse()`

Executes the jsdoc -X command and parses the output into a Javascript object/array; with the specified options.

with Promise...

jsdocx.parse(options)
    .then(function (docs) {
        console.log(docs);
    })
    .catch(function (err) {
        console.log(err.stack);
    });

Or callback...

jsdocx.parse(options, function (err, docs) {
    if (err) {
        console.log(err.stack);
        return;
    }
    console.log(docs);
});

`options`

Object|Array|String - Either an options object or one or more source files to be processed.

Option	Type	Default	Description
`files`	`String\|Array`	`undefined`	Required (if `source` is not set). One or more file/directory paths to be processed.
`source`	`String`	`undefined`	(NOT IMPLEMENTED YET) Required (if `files` is not set). Documented source code to be processed.
`encoding`	`String`	`"utf8"`	Encoding to be used when reading source files.
`recurse`	`Boolean`	`false`	Specifies whether to recurse into subdirectories when scanning for source files.
`pedantic`	`Boolean`	`false`	Specifies whether to treat errors as fatal errors, and treat warnings as errors.
`access`	`String\|Array`	`undefined`	Specifies which symbols to be processed with the given access property. Possible values: `"private"`, `"protected"`, `"public"` or `"all"` (for all access levels). By default, all except private symbols are processed. Note that, if access is not set for a documented symbol, it will still be included, regardless of this option.
`private`	`Boolean`	`false`
`package`	`String`	`undefined`	The path to the `package.json` file that contains the project name, version, and other details. If set to `true` instead of a path string, the first `package.json` file found in the source paths.
`module`	`Boolean`	`true`	Specifies whether to include `module.exports` symbols.
`undocumented`	`Boolean`	`true`	Specifies whether to include undocumented symbols.
`undescribed`	`Boolean`	`true`	Specifies whether to include symbols without a description.
`relativePath`	`String`	`undefined`	When set, all `symbol.meta.path` values will be relative to this path.
`filter`	`Function`	`undefined`	This is used to filter the parsed documentation output array. If a `Function` is passed; it's invoked for each included `symbol`. e.g. `function (symbol) { return symbol; }` Returning a falsy value will remove the symbol from the output. Returning `true` will keep the original symbol. To keep the symbol and alter its contents, simply return an altered symbol object.
`output`	`String\|Object`	`undefined`	Path for a JSON file to be created, containing the output documentation array. Or you can set this to an object for extra options.
↳`output.path`	`String`	`undefined`	Path for a JSON file to be created.
↳`output.indent`	`Boolean\|Number`	`false`	Number of spaces for indentation. If set to `true`, 2 spaces will be used.
↳`output.force`	`Boolean`	`false`	Whether to create parent directories if they don't exist.

Example Output:

See a larger output example here.

[
  {
    "comment": "/**\n * This is the Code class for testing jsdoc-x. */",
    "meta": {
      "range": [
        445,
        9624
      ],
      "filename": "code.js",
      "lineno": 14,
      "path": "../lib",
      "code": {
        "id": "astnode100000001",
        "name": "Code",
        "type": "ClassDeclaration",
        "paramnames": [
          "options"
        ]
      }
    },
    "classdesc": "This is the Code class for testing jsdoc-x.",
    "see": [
      "{@link https://github.com/onury/jsdoc-x|GitHub Project}"
    ],
    "license": "MIT",
    "copyright": "2016, Onur Yıldırım (onur@cutepilot.com)",
    "name": "Code",
    "longname": "Code",
    "kind": "class",
    "scope": "global",
    "description": "Initiates a new instance of the `Code` class.",
    "params": [
      {
        "type": {
          "names": [
            "Object"
          ]
        },
        "description": "Optional. Configuration object.",
        "name": "options"
      },
      {
        "type": {
          "names": [
            "String"
          ]
        },
        "description": "Default: `\"en\"`.\n    Language to be used for API requests that supports language configurations.",
        "name": "options.language"
      },
      {
        "type": {
          "names": [
            "Boolean"
          ]
        },
        "description": "Default: `true`.\n    If set to `true`, the API calls are made over HTTPS, at all times.",
        "name": "options.https"
      }
    ]
  }
]

Change-log:

v0.4.8 (2016-03-19)

If the parent project(s) has jsdoc, ours won't get installed. Since we use a specific file within jsdoc module, we cannot find it via require(). Now, fixed jsdoc path resolver. This will either use the local or from the parent project(s) properly.
Code cleanup. Documentation update.

v0.4.6 (2016-03-19)

Added output option to write JSON file.
Initial commit.

v0.4.0 (2016-03-18)

Using child_process.spawn instead of execFile since the latter has 200kb limit.
Added filter, undocumented, undescribed, module options.
Added jasmine tests.

v0.3.0 (2016-03-17)

Added support for both Promises and callbacks.
Added relativePath option.

v0.1.0 (2016-03-16)

TODO:

options.source for parsing source code. This should create a temp file before parsing.