https://github.com/onury/jsdoc-x
Parser for outputting a Javascript object from documented code via JSDoc's explain (-X) command.
https://github.com/onury/jsdoc-x
documentation javascript jsdoc parse
Last synced: about 1 year ago
JSON representation
Parser for outputting a Javascript object from documented code via JSDoc's explain (-X) command.
- Host: GitHub
- URL: https://github.com/onury/jsdoc-x
- Owner: onury
- License: mit
- Created: 2016-03-19T01:04:29.000Z (over 10 years ago)
- Default Branch: master
- Last Pushed: 2020-01-22T01:30:05.000Z (over 6 years ago)
- Last Synced: 2025-03-27T14:21:17.430Z (about 1 year ago)
- Topics: documentation, javascript, jsdoc, parse
- Language: JavaScript
- Homepage:
- Size: 172 KB
- Stars: 14
- Watchers: 1
- Forks: 7
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# jsdoc-x
[](https://travis-ci.org/onury/jsdoc-x)
[](https://www.npmjs.com/package/jsdoc-x)
[](https://github.com/onury/jsdoc-x/releases)
[](https://github.com/onury/jsdoc-x/blob/master/LICENSE)
[](https://www.npmjs.com/package/jsdoc-x)
[](https://david-dm.org/onury/jsdoc-x)
[](https://github.com/onury/jsdoc-x/graphs/commit-activity)
> © 2020, Onur Yıldırım ([@onury](https://github.com/onury)). MIT License.
Parser for outputting a Javascript object from documented code via JSDoc's explain (`-X`) command.
**Install via NPM**:
```shell
npm i jsdoc-x
```
## Usage:
```js
const jsdocx = require('jsdoc-x');
try {
const docs = await jsdocx.parse('./src/**/*.js');
console.log(docs);
} catch (err) {
console.log(err.stack);
}
```
_(If you like pain, `.parse()` method also supports a callback, instead of promises.)_
See an **output example** [here](https://github.com/onury/jsdoc-x/blob/master/test/output/docs.json).
## `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.md).
[onury]:https://github.com/onury