Package detail

jsdoc-x

onury13.4kMIT4.1.0

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

jsdoc, explain, -X, documentation, parse, doc

readme

jsdoc-x

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

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

Install via NPM:

npm i jsdoc-x

Usage:

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

Parse using Promises...

jsdocx.parse('./src/**/*.js')
    .then(function (docs) {
        console.log(docs);
    })
    .catch(function (err) {
        console.log(err.stack);
    });

Or callback...

var options = { files: './src/**/*.js', hierarchy: true };
jsdocx.parse(options, function (err, docs) {
    if (err) {
        console.log(err.stack);
        return;
    }
    console.log(docs);
});

See an output example here.

`jsdocx.parse(options[, callback])`

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

Param	Type	Description
`options`	`Object\|Array\|String`	Required. Either an options object or one or more source files to be processed. See details below.
`callback`	`Function`	Callback function to be executed in the following signature: `function (err, array) { ... }`. Omit this callback to return a `Promise`. Default: `undefined`

`options`

Object|Array|String - Parse options.

Option	Type	Description
`files`	`String\|Array`	Required (if `source` is not set). One or more file/directory paths to be processed. This also accepts a Glob string or array of globs. e.g. `./src/*/.js` will produce an array of all `.js` files under ./src directory and sub-directories. Default: `undefined`
`source`	`String`	Required (if `files` is not set). Documented source code to be processed. If `files` is also set, this will be ignored. Default: `undefined`
`config`	`Object`	Pass a configuration object to the underlying JSDoc core. This will bypass all parser options. Default: `{}`
`encoding`	`String`	Encoding to be used when reading source files. Default: `"utf8"`
`recurse`	`Boolean`	Specifies whether to recurse into subdirectories when scanning for source files. Default: `false`
`pedantic`	`Boolean`	Specifies whether to treat errors as fatal errors, and treat warnings as errors. Default: `false`
`access`	`String\|Array`	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. Default: `undefined`
`private`	`Boolean`	Shorthand for enabling documentation for `private` access symbols. Default: `false`
`package`	`String`	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. Default: `undefined`
`module`	`Boolean`	Specifies whether to include `module.exports` symbols. Default: `true`
`undocumented`	`Boolean`	Specifies whether to include undocumented symbols. Default: `true`
`undescribed`	`Boolean`	Specifies whether to include symbols without a description. Default: `true`
`ignored`	`Boolean`	Specifies whether to include symbols marked with `@ignore` tag. Default: `true`
`allowUnknownTags`	`Boolean`	Specifies whether to allow unrecognized tags. If set to `false` parsing will fail on unknown tags. Default: `true`
`dictionaries`	`Array`	Indicates the dictionaries to be used. By default, both standard JSDoc tags and Closure Compiler tags are enabled. Default: `["jsdoc", "closure"]`
`includePattern`	`String`	String pattern for defining sources to be included. By default, only files ending in ".js", ".jsdoc", and ".jsx" will be processed. Default: `".+\\.js(doc\|x)?$"`
`excludePattern`	`String`	String pattern for defining sources to be ignored. By default, any file starting with an underscore or in a directory starting with an underscore will be ignored. Default: `"(^\|\\/\|\\\\)_"`
`plugins`	`Array`	Defines the JSDoc plugins to be used. See this guide on JSDoc plugins. Default: `[]`
`relativePath`	`String`	When set, all `symbol.meta.path` values will be relative to this path. Default: `undefined`
`predicate`	`Function\|string`	Alias: `filter`. 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. If a RegExp string is passed, it's executed on the symbol's long name. Default: `undefined`
`hierarchy`	`Boolean`	Specifies whether to arrange symbols by their hierarchy. This will find and move symbols that have a `memberof` property to a `$members` property of their corresponding owners. Also the constructor symbol will be moved to a `$constructor` property of the `ClassDeclaration` symbol; if any. Default: `false`
`sort`	`Boolean\|String`	Specifies whether to sort the documentation symbols. For alphabetic sort, set to `true` or `"alphabetic"`. To group-sort set to `"grouped"`. (Group sorting is done in the following order: by memberof, by scope, by access type, by kind, alphabetic.) To sort by only `"scope"` or `"access"` or `"kind"`, set to corresponding string. (Sorting by kind is done in the following order: constant, package/module, namespace, class, constructor, method, property, enum, typedef, event, interface, mixin, external, other members.) Set to `false` to disable. Default: `false`
`output`	`String\|Object`	Path for a JSON file to be created, containing the output documentation array. Or you can set this to an object for extra options. Default: `undefined`
↳`output.path`	`String`	Path for a JSON file to be created. Default: `undefined`
↳`output.indent`	`Boolean\|Number`	Number of spaces for indentation. If set to `true`, 2 spaces will be used. Default: `false`
↳`output.force`	`Boolean`	Whether to create parent directories if they don't exist. Default: `false`
`debug`	`Boolean`	Specifies whether to include extra information within thrown error messages. Default: `true`

`jsdocx.filter(docs[, options][, predicate])`

Filters the given documentation output array. This is useful if you have an already parsed documentation output.

Param	Type	Description
`docs`	`Array`	Required. Documentation output array.
`options`	`Object`	Filter options. See details below. Default: `undefined`
`predicate`	`Function`	The function invoked per iteration. 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. Default: `undefined`

`options`

Object - Filter options.

Option	Type	Description
`access`	`String\|Array`	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. Default: `undefined`
`package`	`String`	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. Default: `undefined`
`module`	`Boolean`	Specifies whether to include `module.exports` symbols. Default: `true`
`undocumented`	`Boolean`	Specifies whether to include undocumented symbols. Default: `true`
`undescribed`	`Boolean`	Specifies whether to include symbols without a description. Default: `true`
`relativePath`	`String`	When set, all `symbol.meta.path` values will be relative to this path. Default: `undefined`
`hierarchy`	`Boolean`	Specifies whether to arrange symbols by their hierarchy. This will find and move symbols that have a `memberof` property to a `$members` property of their corresponding owners. Also the constructor symbol will be moved to a `$constructor` property of the `ClassDeclaration` symbol; if any. Default: `false`
`sort`	`Boolean\|String`	Specifies whether to sort the documentation symbols. For alphabetic sort, set to `true` or `"alphabetic"`. To additionally group by scope (static/instance) set to `"grouped"`. Set to `false` to disable. Default: `false`

`jsdocx.utils`

Utilities for documentation output and symbols.

Method	Params	Returns	Description
`getFullName(symbol)`	`symbol:Object`	`String`	Alias: `getLongName()`. Gets the full name of the given symbol.
`getCodeName(symbol)`	`symbol:Object`	`String`	Gets the code name of the given symbol.
`getName(symbol)`	`symbol:Object`	`String`	Gets the (short) code-name of the given symbol.
`getSymbolByName(docs, name)`	`docs:Array` `name:String`	`Boolean`	Gets the first matching symbol by the given name.
`getSymbolNames(docs, sorter)`	`docs:Array` `sorter:Function\|String`	`Array`	Builds and gets a flat array of symbol names from the given jsdoc-x parsed output. Pass a comparer function for `sorter` or a pre-defined string `"alphabetic"` or `"grouped"`.
`getKind(symbol)`	`symbol:Object`	`Number`	Gets the kind of the symbol. This is not the same as `symbol.kind`. i.e. JSDoc generates a constructor's kind as `"class"`. This will return `"constructor"`. Enumeration objects are returned as `"enum"`. Function members are returned as `"method"`, non-function members are returned as `"property"` (including getters/setters)...
`getLevels(symbol)`	`symbol:Object\|String`	`Number`	Gets the number of levels for the given symbol or name. e.g. `mylib.prop` has 2 levels.
`getParentName(symbol)`	`symbol:Object\|String`	`Number`	Gets the parent symbol name from the given symbol's name. Note that, this will return the parent name even if the parent symbol does not exist in the documentation. If there is no parent, returns `""` (empty string).
`getParent(symbol)`	`symbol:Object\|String`	`Number`	Gets the parent symbol object from the given symbol object or symbol's name.
`hasDescription(symbol)`	`symbol:Object`	`Boolean`	Checks whether the given symbol has description.
`isCallback(symbol)`	`symbol:Object`	`Boolean`	Checks whether the given symbol is a callback definition.
`isClass(symbol)`	`symbol:Object`	`Boolean`	Checks whether the given symbol is a class.
`isConstant(symbol)`	`symbol:Object`	`Boolean`	Checks whether the given symbol is a marked as a constant.
`isConstructor(symbol)`	`symbol:Object`	`Boolean`	Checks whether the given symbol is a constructor.
`isDeprecated(symbol)`	`symbol:Object`	`Boolean`	Checks whether the given symbol is marked with `@deprecated`.
`isEnum(symbol)`	`symbol:Object`	`Boolean`	Checks whether the given symbol is an enumeration.
`isEvent(symbol)`	`symbol:Object`	`Boolean`	Checks whether the given symbol is an event.
`isExternal(symbol)`	`symbol:Object`	`Boolean`	Checks whether the given symbol is defined outside of the current package.
`isGenerator(symbol)`	`symbol:Object`	`Boolean`	Checks whether the given symbol is a generator function.
`isGlobal(symbol)`	`symbol:Object`	`Boolean`	Checks whether the given symbol has global scope.
`isIgnored(symbol)`	`symbol:Object`	`Boolean`	Checks whether the given symbol is marked with `@ignore`.
`isInner(symbol)`	`symbol:Object`	`Boolean`	Checks whether the given symbol has an inner scope.
`isInstanceMember(symbol)`	`symbol:Object`	`Boolean`	Checks whether the given symbol is an instance member.
`isInstanceMethod(symbol)`	`symbol:Object`	`Boolean`	Checks whether the given symbol is an instance method.
`isInstanceProperty(symbol)`	`symbol:Object`	`Boolean`	Checks whether the given symbol is an instance property.
`isMixin(symbol)`	`symbol:Object`	`Boolean`	Checks whether the given symbol is marked as a mixin (is intended to be added to other objects).
`isNamespace(symbol)`	`symbol:Object`	`Boolean`	Checks whether the given symbol is a namespace.
`isProperty(symbol)`	`symbol:Object`	`Boolean`	Checks whether the given symbol is a property.
`isReadOnly(symbol)`	`symbol:Object`	`Boolean`	Checks whether the given symbol is read-only.
`isMethod(symbol)`	`symbol:Object`	`Boolean`	Checks whether the given symbol is a method.
`isStaticMember(symbol)`	`symbol:Object`	`Boolean`	Checks whether the given symbol is a static member.
`isStaticMethod(symbol)`	`symbol:Object`	`Boolean`	Checks whether the given symbol is a static method.
`isStaticProperty(symbol)`	`symbol:Object`	`Boolean`	Checks whether the given symbol is a static property.
`isTypeDef(symbol)`	`symbol:Object`	`Boolean`	Alias: `isCustomType()`. Checks whether the given symbol is a custom type definition.
`isInterface(symbol)`	`symbol:Object`	`Boolean`	Checks whether the given symbol is marked as an interface that other symbols can implement.
`isPublic(symbol)`	`symbol:Object`	`Boolean`	Checks whether the given symbol has `public` access.
`isPrivate(symbol)`	`symbol:Object`	`Boolean`	Checks whether the given symbol has `private` access.
`isPackagePrivate(symbol)`	`symbol:Object`	`Boolean`	Checks whether the given symbol has `package` private access; indicating that the symbol is available only to code in the same directory as the source file for this symbol.
`isProtected(symbol)`	`symbol:Object`	`Boolean`	Checks whether the given symbol has `protected` access.
`isUndocumented(symbol)`	`symbol:Object`	`Boolean`	Checks whether the given symbol is undocumented. This checks if the symbol has any comments.
`notate(symbol, notation)`	`symbol:Object` `notation:String`	`*`	Gets the value by the given object notation.

Change-log:

See CHANGELOG.md.

changelog

jsdoc-x Changelog

All notable changes to this project will be documented in this file. The format is based on Keep a Changelog and this project adheres to Semantic Versioning.

4.1.0 (2020-01-22)

Changed

Updated JSDoc core dependency to v3.6.3 (latest as of Jan, 2020.)
Added config option that enables passing a custom configuration to the underlying JSDoc core. This bypasses all parser options. (PR by @JustinBeaudry)
Updated other dependencies to their latest versions.

Fixed

An issue where JSDoc core (v3.6.x) produces some duplicate symbols especially when some ES2015 exporting is used within the code.

4.0.3 (2019-01-08)

Changed

filter (or predicate) option now also accepts a regular expression string.
Improved cleanName() inner method that returns clean symbol names.

4.0.0 (2018-11-18)

Changed

Breaking: Requires Node.js v8 or later. This change is due to the core dependency fs-extra update.
Minor improvements.

3.0.0 (2018-02-24)

Changed

Breaking: Requires Node.js v6 or later. (Dropped support for Node v4.)
Improved the symbol sorting logic. You can now sort by scope, by access type, by kind, grouped or alphabetic. See docs.
.isMethod() utility method to return false for getters/setters (which will be treated as properties, not methods).
Updated dependencies.

Added

getKind() utility method. This is not the same as symbol.kind. i.e. JSDoc generates a constructor's kind as "class". This will return "constructor".
$kind property to documented symbols when parsed. See utils.getKind() method to see how it's different than symbol.kind.
Utility methods: getLevels(), getParentName(), getParent(), getKind(), isEvent(), isGenerator(), isCallback(), isConstant(), isInterface(), isExternal(), isMixin(), isPackagePrivate().
More tests for utils.

Fixed

An issue with utils.isClass() method where meta.code.type is not set to ClassDeclaration.
.isProperty() utility method. It'll now return false if symbol is a method/function. This also affects the following methods: .isStaticProperty(), .isInstanceProperty().

2.0.2 (2018-01-18)

Changed

Updated dependencies.

2.0.1 (2017-08-24)

Added

options.debug for .parse() method. Fixes #4.

2.0.0 (2017-08-24)

Changed

Breaking: Requires Node.js v4 or newer.
Updated jsdoc core module from v3.4.3 to v3.5.4. This adds support for ES2015 code, new tags such as @hideconstructor, etc.. (See [all JSDoc changes here][jsdoc-releases]).
Any temporary files generated are now gracefully cleaned up, after parsing is complete.
Updated dependencies to latest versions.

Fixed

An issue where constructor could not be detected due to a JSDoc bug. For example, in ES2015 code, if the constructor is not marked with @constructs the longname is incorrect e.g. ClassName#ClassName instead of ClassName. We fixed this both for utils.getLongName() and for constructor-detection within the hierarchy process.
An issue where some symbols were not moved to $members collection because of its <anonymous>~ prefix. This has occurred when the hierarchy option was enabled.
An issue with a rare case that occurred when a JSDoc comment contained a specific string.
utils.getLongName() (was broken after JSDoc updated).

1.3.3 (2017-03-10)

Added

ignored boolean option that specifies whether to exclude symbols marked with @ignore tag in the output.
utils.isIgnored().
utils.isDeprecated().

1.3.2 (2017-03-09)

Changed

Improved symbols sorting logic/performance.

Added

utils.getSymbolNames() utility method.

1.3.0 (2017-03-05)

Changed

Updated dependencies to latest versions.

Added

Options: allowUnknownTags, dictionaries, includePattern, excludePattern.
JSDoc plugin support via the new plugins option.

1.1.0 (2016-08-13)

Added

Utility methods: utils.isPublic(), utils.isPrivate(), utils.isProtected().

Fixed

Constructors would still show up in the output even though @private is set.

1.0.8 (2016-06-06)

Changed

Sort options now sorts with $longname.

Added

JSDoc overwrites the longname and name of the symbol, if it has an alias. Now we additionally output a $longname property with each symbol, that returns the correct/original long name. See issue at JSDoc repo.
Utility methods: utils.getCodeName(), utils.isInner() and utils.isTypeDef() (alias: utils.isCustomType()).

Fixed

utils.getFullName() (alias: utils.getLongName()).

1.0.5 (2016-05-30)

Added

Utility methods utils.notate() and utils.isModule().

Fixed

sort option. Also symbol.properties are sorted, as well as the symbols.
utils.isMethod(). Added alias utils.isFunction()
utils.isClass().

1.0.2 (2016-05-10)

Fixed

Parsing an array of files was broken. Fixed. (PR #2)

1.0.1 (2016-05-07)

Fixed

utils.isMethod().

1.0.0 (2016-05-05)

Added

glob support for files option of .parse() method.
source option for .parse() method.
hierarchy option for .parse() method.
sort option for .parse() method.
.filter() method for use with (already parsed) documentation array.
utils as a utility module for documentation symbols.

0.4.8 (2016-03-19)

Fixed

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.

[0.4.6] (2016-03-19)

Added

output option to write JSON file.

[0.4.0] (2016-03-18)

Changed

Using child_process.spawn instead of execFile since the latter has 200kb limit.

Added

filter, undocumented, undescribed, module options.
Jasmine tests.

[0.3.0] (2016-03-17)

Added

Support for both Promises and callbacks.
relativePath option.

[0.1.0] (2016-03-16)

Initial.