@carbon-io/carbon-jsdoc
v0.0.30
Published
jsdoc plugin for parsing carbon jsdoc output
Downloads
36
Keywords
Readme
carbon-jsdoc
Global npm package to generate docs from jsdoc comments in the carbon-io codebase.
Requirements
- jsdoc (http://usejsdoc.org/) (3.5.4)
- Install with npm: npm install -g [email protected]
Installation
npm install -g [email protected]
npm install -g @carbon-io/carbon-jsdoc
Use
Single module use:
- carbon-jsdoc must be run from the root of a carbon-io module
- Can be passed an output directory via -d (--destination) option, otherwise it will write to MODULE_ROOT/docs/ref
- carbon-jsdoc runs recusively, and assumes that it will run on MODULE_ROOT/index.js and MODULE_ROOT/lib.
- If a module's structure differs from the above, carbon-jsdoc can be told where to look via a file at the root of the module called '.jsdoc-directories', which contains a json object of the following form:
{ "paths": ["paths", "where", "carbon-jsdoc", "should", "scan"] }
Example .jsdoc-directories (from carbond):
{ "paths": ["./lib"] }
- To run:
From module root:
$ carbon-jsdoc
Workflow from changing code to live docs
- Change code in submodule (e.g. carbond)
- Bump tag and push to git
- A pre-commit hook will run carbon-jsdoc, and then add the docs/ref directory, adding the newly generated .rst files to the commit
- From the root of carbon-io:
- git submodule update --init --recursive
- cd .git-cmds and ./git-update-docs
- A pre-commmit hook on carbon-io will run "generate-toc-list" and "git add docs/ref/index.rst" to generate the toc list based on the files in the tree, and add the new index to the commit
Tagging
Namespaces
- Only need to be defined once
- Use the @namespace tag (http://usejsdoc.org/tags-namespace.html)
- Use full namespace in tag (e.g. @namespace carbond.limiter)
- If there are no properties or functions that are members of a namespace, an .rst file will not be generated
Classes
- 3 types of class definitions
- oo()
- Traditional javascript class
- I.e. any class defined in carbon modules lacking a _C function
- ES6 classes (future)
- @extends (http://usejsdoc.org/tags-augments.html) is optional
- If there are no properties or functions that are members of a class, an .rst file will not be generated
oo() tags:
module.exports = oo({ /************************** * @constructs Klazz * @description Description of Klazz * @memberof namespace * @extends fullnamespace.ParentKlazz */ _C: function() { ... } })
Traditional javascript class tags:
/** * @class Klazz * @description Description of Klazz * @memberof namespace * @extends fullnamespace.ParentKlazz */ function Klazz() { } Klazz.prototype = {}
ES6 tags:
/** * @memberof namespace * @description Description of Klazz * @extends fullnamespace.ParentKlazz */ class Klazz {}
- 3 types of class definitions
Properties
- Use the @property tag (http://usejsdoc.org/tags-property.html) (Without a @property tag, properties will not be documented)
- If a property is defined BEFORE the class, it must be tagged with @memberof, including the FULL namespace (e.g. carbond.Endpoint)
- Default values would be documented like this:
@property {type} [propertyName=defaultValue] -- Description
- Properties defined without default values will be marked as required
- Multiple types would be documented like this: {type1 | type2 | ...}
- @readonly (http://usejsdoc.org/tags-readonly.html) is optional
Example:
/********************************************** * @property {type} propertyName -- Description * @readonly */ this.propertyName = undefined
Functions
- Use the following tags:
- If a function is defined BEFORE the class, it must be tagged with @memberof, including the FULL namespace (e.g. carbond.Endpoint)
- @method (http://usejsdoc.org/tags-function.html) (Without a @method tag, functions will not be documented)
- @param (http://usejsdoc.org/tags-param.html)
- @description (http://usejsdoc.org/tags-description.html)
- @returns (http://usejsdoc.org/tags-returns.html)
- @override (http://usejsdoc.org/tags-override.html)
- @throws (http://usejsdoc.org/tags-throws.html)
- @returns (http://usejsdoc.org/tags-returns.html)
- return type and description should be "undefined" if function is void
@returns {undefined} -- undefined
- functions whose name begins with a leading underscore will not be added to the documentation, even with tags
Example:
/******************************************************** * @method methodName * @description Function description * @param {type} parameterName -- Parameter description * @returns {type} -- Return type description */ methodName: function(parameterName) { returns x }
Linking to internal entities (classes, properties, and typedefs)
- When entering a link to another entity within a type description, add one of the following prefixes to the full namespace of the entity, depending on what it is:
- "prop:" for properties
- e.g. {prop:carbond.Endpoint.property}
- "typedef:" for typedefs
- e.g. {typedef:carbond.Endpoint.typedef}
- "class:" for classes
- e.g. {class:carbond.Endpoint}
- "prop:" for properties
- Type links lacking one of the above prefixes will default to linking to "class" types
- When linking to another entity within the description of an entity (e.g. @description or @default), use @link:
- e.g. @property {class:carbond.Service} service -- This endpoint's {@link class:carbond.Service}
- When entering a link to another entity within a type description, add one of the following prefixes to the full namespace of the entity, depending on what it is:
Linking to external entities
- When linking to classes that are not in carbon-io, (e.g. Express), use the @external and @see tags to define a link to the documentation, and have the extension class tags @extend this object
- If the class member tags are purely virtual, that is, they are not attached to any code object, class member tags must use the @name tag\
- Only link to the top level of the external documentation, in order to not rely on anchors that may change in the future
/*************************************************************************************************** * @external express * @description The express namespace * @see https://expressjs.com/en/4x/api.html */
- Then define extended classes and their members like normal:
/*************************************************************************************************** * @class Request * @memberof carbond * @description The Request object represents the HTTP request and has properties for the request * query string, parameters, body, HTTP headers, and so on * @extends external:express */ /*************************************************************************************************** * @name test * @property {object} test -- test property * @memberof carbond.Request */
Notes
+ The star separators ('/*********...') can be of arbitrary length > 1 if they are to be parsed as jsdoc comments