@carbon-io/carbon-jsdoc

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 jsdoc@3.5.4

Installation

npm install -g jsdoc@3.5.4
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 {}
  

• 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}
  • 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}

• 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