Skip to content

Latest commit

 

History

History
106 lines (84 loc) · 3.47 KB

README.md

File metadata and controls

106 lines (84 loc) · 3.47 KB
Raw

JSDoc MemberOf Namespace

JSDoc plugin to automatically generate memberof namespace tags

This plugin creates a @memberof tag, if missing, from the @namespace tag defined in index.js (index scope) or the file itself (module scope). This enables for a complex project with many modules or packages to be documented easily without needing to manually add @memberof tags to every comment to keep documentation organised.

Sample documentation for test module is available on docs page.

Installation and Configuration

JSDoc should be installed and configured.

  1. Install jsdoc-memberof-namespace

    npm install jsdoc-memberof-namespace --save-dev

  2. Add node_modules/jsdoc-memberof-namespace to plugins in JSDoc configuration file

    Sample conf.json

    {
  "source": {
    "include": "src"
  },
  "plugins": [
    "plugins/markdown",
    "node_modules/jsdoc-memberof-namespace"
  ],
  "opts": {
    "recurse": true
  }
}

Usage

// index.js
/**
 * Acme Corporation
 * @namespace acme
 */
// Product.js
/**
 * Base product
 * Documented as acme.Product
 */
class Product {
    /**
     * Add product to basket
     * Documented as acme.Product#buy
     */
    buy() { }
}

Multiple namespaces can be defined in multiple places and the closest applicable namespace will be used:

  1. In the current file (last namespace defined if multiple)
  2. In the index.js in the same directory as the file
  3. In the index.js in any parent directory closest to the file

Index Scope

Namespace can be defined in index.js located in same directory as the file or any of the parent directories. It is the easiest way to document your project by simply adding @namespace once alongside your re-exports.

Module Scope

Namespace can be defined in the file itself. This namespace will only apply to other documentation comments in the file and only those defined after the namespace. The behaviour is similar to @module tag.

Notes

  • Only classes, constants, and functions are processed, for other kinds to be included please submit an issue with sample code
  • Prefix references with namespaces as you normally would even if your IDE highlights them as (yet) unresolved 
    /**
 * @type {acme.Foo}
 * @param {acme.Bar} bar
 */
  • Enable useLongnameInNav default template configuration option to use fully qualified names for navigation 
    "templates": {
  "default": {
    "includeDate": false,
    "useLongnameInNav": true
  }
}
  • Add --debug command-line option to increase JSDoc logging level and look for messages with [JMN] prefix