node package manager
Loosely couple your services. Use Orgs to version and reuse your code. Create a free org »

jsdoc-x

jsdoc-x

build-status npm release license downloads dependencies maintained

© 2017, 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 Default Description
options Object|Array|String Required. Either an options object or one or more source files to be processed. See details below.
callback Function undefined Callback function to be executed in the following signature: `function (err, array) { ... }`. Omit this callback to return a `Promise`.

options

Object|Array|String - Parse options.

Option Type Default Description
files String|Array undefined 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.
source String undefined Required (if files is not set). Documented source code to be processed. If files is also set, this will be ignored.
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.
ignored Boolean true Specifies whether to include symbols marked with @ignore tag.
allowUnknownTags Boolean true Specifies whether to allow unrecognized tags. If set to `false` parsing will fail on unknown tags.
dictionaries Array ["jsdoc", "closure"] Indicates the dictionaries to be used. By default, both standard JSDoc tags and Closure Compiler tags are enabled.
includePattern String ".+\\.js(doc|x)?$" String pattern for defining sources to be included. By default, only files ending in ".js", ".jsdoc", and ".jsx" will be processed.
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.
plugins Array [] Defines the JSDoc plugins to be used. See this guide on JSDoc plugins.
relativePath String undefined When set, all symbol.meta.path values will be relative to this path.
predicate Function undefined 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.
hierarchy Boolean false 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.
sort Boolean|String false 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.
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.
debug Boolean true Specifies whether to include extra information within thrown error messages.

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

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

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

options

Object - Filter options.

Option Type Default Description
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.
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.
hierarchy Boolean false 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.
sort Boolean|String false 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.

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".
hasDescription(symbol) symbol:Object Boolean Checks whether the given symbol has description.
isClass(symbol) symbol:Object Boolean Checks whether the given symbol is a class.
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.
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.
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.
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.
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.