Coding Standard‐1 JSDoc - JUCSE49-Mavericks/Smart-Class-Routine-Management-System GitHub Wiki

JSDoc 3 is an API documentation generator for JavaScript. It creates an HTML documentation site based on the comments you add to your code. This documentation helps to describe the API of your JavaScript application or library.

To add documentation comments to your JavaScript code, follow these steps:

1. Start with a JSDoc Comment Block: Documentation comments should be placed directly before the code they document. Each comment block starts with /** and ends with */.

   /**
    * This is a description of the foo function.
    */
   function foo() {
   }

2. Use JSDoc Tags: Tags provide additional information about the code. Here are some commonly used tags:

   • @param {Type} name - Description: Describes a function parameter.
   • @returns {Type} Description: Describes the return value of a function.
   • @constructor: Indicates that a function is a constructor.
   • @namespace: Defines a namespace.
   • @module: Indicates a module.
   • @example: Provides usage examples.

   Example with tags:

   /**
    * Represents a book.
    * @constructor
    * @param {string} title - The title of the book.
    * @param {string} author - The author of the book.
    */
   function Book(title, author) {
   }

After commenting your code, you can generate the documentation website using JSDoc 3.

1. Install JSDoc: If you haven’t already installed JSDoc, you can do so using npm:

   npm install -g jsdoc

2. Run the Documentation Generator: Use the command line to generate the documentation. Run the following command in your terminal, replacing book.js with the path to your JavaScript file:

   jsdoc book.js

   This command generates an out/ directory in your current working directory containing the HTML documentation.

3. View the Documentation: Open the generated HTML files in the out/ directory using a web browser to view your documentation.

By default, JSDoc uses the built-in "default" template. However, you can customize this template or create a new one:

• Edit Default Template: Modify the built-in template files located in the node_modules/jsdoc/templates/default directory.
• Create a New Template: Create a custom template by following the JSDoc template guidelines and set it in the JSDoc configuration.

Namepaths in JSDoc are used to uniquely identify and refer to different parts of your code, such as methods, properties, and nested functions. They help in disambiguating between various members of classes, objects, and functions.

Here’s how to use namepaths to refer to different parts of your code:

1. Instance Members:

   MyConstructor#instanceMember

2. Static Members:

   MyConstructor.staticMember

3. Inner Members:

   MyConstructor~innerMember

Consider the following example where we have a Person constructor with an instance method, an inner function, and a static method:

/** @constructor */
Person = function() {
    this.say = function() {
        return "I'm an instance.";
    }

    function say() {
        return "I'm inner.";
    }
}

Person.say = function() {
    return "I'm static.";
}

var p = new Person();
p.say();      // "I'm an instance."
Person.say(); // "I'm static."

To refer to these methods using namepaths:

• Instance Method:

  Person#say

• Static Method:

  Person.say

• Inner Method:

  Person~say

The inner method say is not directly accessible from outside the function but can be referred to with Person~say. This is useful if you expose or return such inner methods through other means.

If you have nested constructors or members, you can chain the namepaths together. For example:

/** @constructor */
Person = function() {
    /** @constructor */
    this.Idea = function() {
        this.consider = function(){
            return "hmmm";
        }
    }
}

var p = new Person();
var i = new p.Idea();
i.consider(); // "hmmm"

To refer to the consider method of the Idea constructor:

Person#Idea#consider

1. Modules:

   • Use @module and prefix the name with module::

     /** A module. Its name is module:foo/bar. */

2. Externals:

   • Use @external and prefix the name with external::

     /** The built-in string object. Its name is external:String. */

3. Events:

   • Use @event and prefix the name with event::

     /** An event. Its name is module:foo/bar.event:MyEvent. */

When dealing with objects or properties with special characters in their names, use quotes around the names:

/** @namespace */
var chat = {
    /**
     * Refer to this by {@link chat."#channel"}.
     * @namespace
     */
    "#channel": {
        /**
         * Refer to this by {@link chat."#channel".open}.
         * @type {boolean}
         * @defaultvalue
         */
        open: true,
        /**
         * Internal quotes have to be escaped by backslash.
         * {@link chat."#channel"."say-\"hello\""}.
         */
        'say-"hello"': function (msg) {}
    }
};

/**
 * Define an event in our {@link chat."#channel"} namespace.
 * @event chat."#channel"."op:announce-motd"
 */

In the above example, you use quotes and backslashes to handle special characters in names:

• Namespace with Special Characters:

  chat."#channel"

• Event with Special Characters:

  chat."#channel"."op:announce-motd"

JSDoc can be run with various command-line options to customize how documentation is generated. Here's a breakdown of the available options and their usage:

To generate documentation, run JSDoc with paths to the source code files:

/path/to/jsdoc yourSourceCodeFile.js anotherSourceCodeFile.js ...

You can also include a Markdown file or a file named "README" to add content to the documentation's front page.

• -a <value>, --access <value>

  • Description: Filter symbols by access level: private, protected, public, or undefined, or use all for all access levels. By default, private symbols are excluded.

• -c <value>, --configure <value>

  • Description: Path to a JSDoc configuration file. Defaults to conf.json or conf.json.EXAMPLE in the installation directory.

• -d <value>, --destination <value>

  • Description: Path to the output folder for generated documentation. Use console to print data to the console. Defaults to ./out.

• --debug

  • Description: Enable logging of information for debugging JSDoc issues.

• -e <value>, --encoding <value>

  • Description: Encoding for reading source files. Defaults to utf8.

• -h, --help

  • Description: Display help information about command-line options.

• --match <value>

  • Description: Run tests with names containing the specified value.

• --nocolor

  • Description: Disable color in console output for tests. Enabled by default on Windows.

• -p, --private

  • Description: Include symbols marked with the @private tag in the documentation. Private symbols are excluded by default.

• -P, --package

  • Description: Path to the package.json file containing project details. Defaults to the first package.json found in the source paths.

• --pedantic

  • Description: Treat errors as fatal and warnings as errors. Defaults to false.

• -q <value>, --query <value>

  • Description: Query string for global variable env.opts.query. Example: foo=bar&baz=true.

• -r, --recurse

  • Description: Recurse into subdirectories when scanning for source files and tutorials.

• -R, --readme

  • Description: Path to the README.md file to include in the documentation. Defaults to the first README.md found in the source paths.

• -t <value>, --template <value>

  • Description: Path to the template for generating output. Defaults to templates/default.

• -T, --test

  • Description: Run JSDoc's test suite and print results to the console.

• -u <value>, --tutorials <value>

  • Description: Directory for JSDoc to search for tutorials. If omitted, no tutorial pages will be generated.

• -v, --version

  • Description: Display JSDoc's version number and exit.

• --verbose

  • Description: Log detailed information during execution. Defaults to false.

• -X, --explain

  • Description: Dump all doclets to the console in JSON format and exit.

1. Generate Documentation with Configuration File:

   /path/to/jsdoc src -r -c /path/to/my/conf.json -d docs

2. Run JSDoc Tests with Specific Keyword:

   /path/to/jsdoc -T --match tag --verbose

1. JSON File

   • This format is straightforward and may include comments.
   • Example:

     {
         "plugins": ["plugins/markdown"]
     }

2. CommonJS Module

   • This format is a JavaScript file that exports a configuration object.
   • Example:

     'use strict';
     
     module.exports = {
         plugins: ['plugins/markdown']
     };

Use the -c command-line option to specify the configuration file:

jsdoc -c /path/to/conf.json

If no configuration file is provided, JSDoc uses these default settings:

{
    "plugins": [],
    "recurseDepth": 10,
    "source": {
        "includePattern": ".+\\.js(doc|x)?$",
        "excludePattern": "(^|\\/|\\\\)_"
    },
    "sourceType": "module",
    "tags": {
        "allowUnknownTags": true,
        "dictionaries": ["jsdoc","closure"]
    },
    "templates": {
        "cleverLinks": false,
        "monospaceLinks": false
    }
}

• Plugins: No plugins are loaded.
• Recurse Depth: Searches up to 10 levels deep.
• Source Patterns: Includes .js, .jsdoc, .jsx; excludes files starting with _.
• Source Type: Assumes ES2015 modules.
• Tags: Allows unknown tags and uses both JSDoc and Closure tags.
• Templates: {@link} tags are rendered in plain text.

To enable plugins, list their paths in the plugins array:

{
    "plugins": [
        "plugins/markdown",
        "plugins/summarize"
    ]
}

Control the recursion depth with the recurseDepth option:

{
    "recurseDepth": 10
}

Use the source object to include or exclude files and directories:

{
    "source": {
        "include": ["path/to/files"],
        "exclude": ["path/to/ignore"],
        "includePattern": ".+\\.js(doc|x)?$",
        "excludePattern": "(^|\\/|\\\\)_"
    }
}

Specify the type of JavaScript files with sourceType:

{
    "sourceType": "module"
}

Include command-line options in the configuration file’s opts section:

{
    "opts": {
        "template": "templates/default",
        "encoding": "utf8",
        "destination": "./out/",
        "recurse": true,
        "tutorials": "path/to/tutorials"
    }
}

Adjust tag handling with the tags options:

{
    "tags": {
        "allowUnknownTags": true,
        "dictionaries": ["jsdoc", "closure"]
    }
}

Customize the appearance of the generated documentation:

{
    "templates": {
        "cleverLinks": false,
        "monospaceLinks": false
    }
}

• cleverLinks: If true, inline links are rendered based on their type.
• monospaceLinks: If true, all links are rendered in monospace.

For more advanced configurations, refer to the JSDoc documentation and examples provided within the JSDoc source or community plugins.

By default, JSDoc generates pretty-printed versions of your source files and links to them. To disable this and remove the links, set:

{
  "templates": {
    "default": {
      "outputSourceFiles": false
    }
  }
}

To copy additional static files (like images or stylesheets) to the output directory:

• Include static files: Define paths whose contents should be copied.

• Exclude static files: Define paths that should be excluded.

• Include files by pattern: Use a regex pattern to include files.

• Exclude files by pattern: Use a regex pattern to exclude files.

Example configuration to copy a directory of images:

{
  "templates": {
    "default": {
      "staticFiles": {
        "include": [
          "./myproject/static"
        ]
      }
    }
  }
}

To omit the current date from the footer:

{
  "templates": {
    "default": {
      "includeDate": false
    }
  }
}

To display the full longname of symbols in the navigation column instead of a shortened version:

{
  "templates": {
    "default": {
      "useLongnameInNav": true
    }
  }
}

To use your own layout file, specify the path to the custom layout file:

{
  "templates": {
    "default": {
      "layoutFile": "./path/to/your/layout.tmpl"
    }
  }
}

Here's an example configuration file that incorporates all the above customizations:

{
  "templates": {
    "default": {
      "outputSourceFiles": false,
      "staticFiles": {
        "include": [
          "./myproject/static"
        ],
        "excludePattern": ".*\\.ignore$"
      },
      "includeDate": false,
      "useLongnameInNav": true,
      "layoutFile": "./custom/layout.tmpl"
    }
  }
}

To use this configuration, save it as a JSON file (e.g., conf.json) and run JSDoc with the -c option:

jsdoc -c /path/to/conf.json

This will apply the specified customizations to your JSDoc documentation.

JSDoc is a popular tool for generating documentation for JavaScript code. Here's a summary of how to use block and inline tags effectively in JSDoc comments:

Block tags are used to provide detailed information about the code and are placed at the top level of a JSDoc comment. Each block tag must be followed by a line break, except for the last block tag in the comment. Block tags always start with an at sign (@). Examples of block tags include:

• @param: Describes a parameter of a function.
• @returns or @return: Describes the return value of a function.
• @typedef: Defines a custom type.
• @example: Provides an example of how to use a function or method.

Example:

/**
 * Set the shoe's color.
 *
 * @param {string} color - The shoe's color.
 * @returns {void}
 */
Shoe.prototype.setColor = function(color) {
    // ...
};

Inline tags are used within the text of a block tag or description. They are enclosed in curly braces ({ and }). Inline tags also begin with an at sign (@) but are used within the description or block tags. They help link to other parts of the documentation.

Example:

/**
 * Set the shoe's color. Use {@link Shoe#setSize} to set the shoe size.
 *
 * @param {string} color - The shoe's color.
 */
Shoe.prototype.setColor = function(color) {
    // ...
};

You can use inline tags within block tags or descriptions. This is useful for referencing other functions, types, or documentation directly within the text.

Example:

/**
 * Set the shoe's color.
 *
 * @param {SHOE_COLORS} color - The shoe color. Must be an enumerated
 * value of {@link SHOE_COLORS}.
 */
Shoe.prototype.setColor = function(color) {
    // ...
};

When using multiple block tags in a JSDoc comment, ensure they are separated by line breaks.

Example:

/**
 * Set the color and type of the shoelaces.
 *
 * @param {LACE_COLORS} color - The shoelace color.
 * @param {LACE_TYPES} type - The type of shoelace.
 */
Shoe.prototype.setLaceType = function(color, type) {
    // ...
};

To create and enable a JSDoc plugin, follow these two main steps:

1. Create a JavaScript Module: Write your plugin code in a JavaScript module. This module should export the necessary functions and objects that JSDoc will use.

2. Configure JSDoc: Add the path to your plugin module in the plugins array of JSDoc's configuration file. You can use an absolute or relative path. For example, if your plugin is located in plugins/shout.js, you should configure it like this:

   {
       "plugins": ["plugins/shout"]
   }

   JSDoc executes plugins in the order they appear in the plugins array.

JSDoc 3's plugin system allows extensive control over the documentation generation process. Here’s how you can utilize different features:

Plugins can register handlers for specific named events. Here’s how you can create a plugin that handles the newDoclet event:

exports.handlers = {
    newDoclet: function(e) {
        // Handle the creation of a new doclet
    }
};

Events and Their Usage:

• parseBegin: Fired before JSDoc starts parsing source files. You can modify which files are parsed by changing the sourcefiles array.

• fileBegin: Fired before parsing each file. Useful for per-file initialization.

• beforeParse: Fired before parsing begins. You can modify the source code here (e.g., add or remove comments).

• jsdocCommentFound: Triggered when a JSDoc comment is found. Allows modification of comment contents before processing.

• symbolFound: Fired for each symbol (variable, function, etc.) found in the code. You can access the symbol’s details through this event.

• newDoclet: Fired when a new doclet is created. You can modify the properties of the doclet.

• fileComplete: Fired when a file has been parsed. Useful for per-file cleanup.

• parseComplete: Fired after all source files are parsed. Allows final adjustments based on all parsed doclets.

• processingComplete: Fired after JSDoc updates the parse results with inherited and borrowed symbols.

Plugins can define new tags or modify existing ones using the defineTags function. Here’s an example:

exports.defineTags = function(dictionary) {
    dictionary.defineTag('instance', {
        onTagged: function(doclet, tag) {
            doclet.scope = "instance";
        }
    });
};

You can also define tag synonyms:

dictionary.defineTag('exception', { /* options */ })
    .synonym('throws');

Plugins can define node visitors to process each node in the abstract syntax tree (AST). Use the astNodeVisitor object to visit nodes:

exports.astNodeVisitor = {
    visitNode: function(node, e, parser, currentSourceName) {
        // Process each AST node
    }
};

Parameters for visitNode:

• node: The AST node in question.
• e: The event associated with the node.
• parser: The JSDoc parser instance.
• currentSourceName: The name of the file being parsed.

If your plugin needs to report errors, use the methods from the jsdoc/util/logger module:

• logger.warn: Warn the user about potential issues.
• logger.error: Report recoverable errors.
• logger.fatal: Report critical errors that should stop JSDoc from running.

Here’s an example of using logger.error:

var logger = require('jsdoc/util/logger');

exports.handlers = {
    newDoclet: function(e) {
        // Handle new doclet creation

        if (somethingBadHappened) {
            logger.error('An error occurred!');
        }
    }
};

This approach enhances the user experience compared to directly throwing errors. Avoid using the deprecated jsdoc/util/error module for error reporting.

Here's an overview of how to enable and configure the JSDoc Markdown plugin:

JSDoc includes a Markdown plugin that converts Markdown-formatted text to HTML. This plugin is available in JSDoc 3.2.2 and later versions, using the marked Markdown parser.

Important Note: When using the Markdown plugin, ensure each line of your JSDoc comments begins with a leading asterisk (*). This is necessary because JSDoc's parser might remove asterisks used for Markdown formatting if they are not included.

The Markdown plugin processes Markdown-formatted text in the following default JSDoc tags:

• @author
• @classdesc
• @description (including untagged descriptions at the start of a JSDoc comment)
• @param
• @property
• @returns
• @see
• @throws

To enable the Markdown plugin, add plugins/markdown to the plugins array in your JSDoc configuration file. Here’s how you can do it:

JSON Configuration File Example:

{
    "plugins": ["plugins/markdown"]
}

By default, only specific tags are processed for Markdown. To include Markdown processing in additional tags, use the markdown.tags property in your JSDoc configuration file. This property should contain an array of additional doclet properties that can contain Markdown text.

Example Configuration:

{
    "plugins": ["plugins/markdown"],
    "markdown": {
        "tags": ["foo", "bar"]
    }
}

In this example, the tags foo and bar will also be processed for Markdown.

To prevent the Markdown plugin from processing certain default JSDoc tags, use the markdown.excludeTags property. This property should be an array of tags that should not be processed for Markdown text.

Example Configuration:

{
    "plugins": ["plugins/markdown"],
    "markdown": {
        "excludeTags": ["author"]
    }
}

In this example, the author tag is excluded from Markdown processing.

By default, the Markdown plugin does not hard-wrap text at line breaks. To enable hard-wrapping, set the markdown.hardwrap property to true.

Example Configuration:

{
    "plugins": ["plugins/markdown"],
    "markdown": {
        "hardwrap": true
    }
}

To add id attributes to each HTML heading automatically based on the heading’s text, set the markdown.idInHeadings property to true.

Example Configuration:

{
    "plugins": ["plugins/markdown"],
    "markdown": {
        "idInHeadings": true
    }
}

Copyright © 2011 the contributors to the JSDoc documentation. This documentation is open source and licensed under the Creative Commons Attribution-ShareAlike 3.0 Unported License.

Feel free to modify the configurations as needed to suit your project’s requirements!

JSDoc allows you to include detailed tutorials alongside your API documentation. This feature is useful for providing guides, "getting started" instructions, or step-by-step processes for implementing features.

To include tutorials, use the --tutorials or -u option when running JSDoc, and specify the directory containing your tutorial files. For example:

jsdoc -u path/to/tutorials path/to/js/files

JSDoc will search for tutorial files with the following extensions:

• .htm
• .html
• .markdown (converted from Markdown to HTML)
• .md (converted from Markdown to HTML)
• .xhtml
• .xml (treated as HTML)

By default, JSDoc uses the filename as the title for each tutorial, and all tutorials are treated as being at the same level. You can customize this using a JSON file to define titles, order, and hierarchy.

1. Tree of Objects Format

   Create a JSON file where each tutorial can have a children property that lists its sub-tutorials. For example:

   {
       "tutorial1": {
           "title": "Tutorial One",
           "children": {
               "childA": {
                   "title": "Child A"
               },
               "childB": {
                   "title": "Child B"
               }
           }
       },
       "tutorial2": {
           "title": "Tutorial Two"
       }
   }

2. Top-Level Object Format

   Use a JSON file where each property is a tutorial object. List child tutorials by name in the children array. For example:

   {
       "tutorial1": {
           "title": "Tutorial One",
           "children": ["childA", "childB"]
       },
       "tutorial2": {
           "title": "Tutorial Two"
       },
       "childA": {
           "title": "Child A"
       },
       "childB": {
           "title": "Child B"
       }
   }

   Note: Providing individual .json files for each tutorial is deprecated and not recommended for new projects.

There are two primary ways to link to tutorials from your API documentation:

1. @tutorial Block Tag

   Use the @tutorial block tag in a JSDoc comment to include a link to the tutorial. For example:

   /**
    * Class representing a socket connection.
    *
    * @class
    * @tutorial socket-tutorial
    */
   function Socket() {}

2. {@tutorial} Inline Tag

   Use the {@tutorial} inline tag within another JSDoc tag to link to a tutorial. By default, JSDoc will use the tutorial’s title as the link text. For example:

   /**
    * Class representing a socket connection. See {@tutorial socket-tutorial}
    * for an overview.
    *
    * @class
    */
   function Socket() {}

By following these guidelines, you can enhance your API documentation with detailed tutorials and make it easier for users to understand and utilize your API.

Incorporating information from your project's package.json file into JSDoc documentation can be helpful for displaying details like the project's name and version number. JSDoc can automatically use information from this file when generating documentation.

There are two main methods to include your package.json file in JSDoc:

1. Including the Package File in Source Paths

   Add the path to your package.json file alongside your JavaScript files when running JSDoc. JSDoc will use the first package.json file it finds in the specified source paths.

   Example:

   jsdoc path/to/js path/to/package/package.json

2. Using the -P/--package Command-Line Option

   Specify the path to your package.json file using the -P or --package command-line option. This method overrides the package files found in your source paths.

   Example:

   jsdoc --package path/to/package/package.json path/to/js

• The package.json file must follow npm's package format to be correctly processed by JSDoc.
• The -P/--package option takes precedence over any package.json files found in your source paths. If you use this option, JSDoc will ignore other package.json files that might be in the source paths.

By using these methods, you ensure that your project's metadata is accurately reflected in the generated documentation, providing clear and useful information about the project.

Including a README file in your JSDoc documentation can be a great way to provide an overview or additional information about your project. JSDoc can integrate content from a README file into the generated documentation.

There are two primary methods to include your README file in JSDoc:

1. Including the README File in Source Paths

   Specify the path to a README.md file alongside your JavaScript files when running JSDoc. JSDoc will use the first README.md file it finds in the specified source paths.

   Example:

   jsdoc path/to/js path/to/readme/README.md

2. Using the -R/--readme Command-Line Option

   Use the -R or --readme command-line option to specify the path to your README file. This method allows the README file to have any name and extension, as long as it is in Markdown format. This option takes precedence over any README.md files found in your source paths.

   Example:

   jsdoc --readme path/to/readme/README.md path/to/js

• When using JSDoc's default template, the contents of the README file will be rendered in HTML and included in the index.html file of the generated documentation.
• The -R/--readme option allows for greater flexibility in naming and locating the README file compared to relying on it being named README.md and located in the source paths.

By including a README file, you enhance the documentation with important context and information about your project, making it more accessible and informative for users and developers.

JSDoc is distributed under the Apache License, Version 2.0. This license allows both commercial and non-commercial use, provided that all conditions of the license are met.

Key Points of the Apache License, Version 2.0:

• You can freely use, modify, and distribute the software.
• You must include a copy of the license with any substantial portions of the software.
• If you modify the software and distribute it, you must include a prominent notice stating that you have changed the files.
• There is no warranty for the software, and the software is provided "as-is."

Third-Party Software: JSDoc may include or depend on third-party software packages. Each of these third-party packages is governed by its own license.

For Detailed Licensing Information:

• Refer to the LICENSE.md file in the JSDoc repository or distribution for specific details about the licensing of JSDoc and any third-party software it includes or depends on.

By adhering to these licensing terms, you ensure that you comply with the legal requirements and respect the rights of the original authors of JSDoc and any third-party components.

Official Documentation and Resources:

1. Getting Started with JSDoc

   • A quick start to documenting JavaScript with JSDoc.

2. Using Namepaths with JSDoc

   • A guide to using namepaths with JSDoc.

3. Command-line Arguments to JSDoc

   • About command-line arguments to JSDoc.

4. Configuring JSDoc with a Configuration File

   • How to configure JSDoc using a configuration file.

5. Configuring JSDoc's Default Template

   • How to configure the output from JSDoc's default template.

6. Block and Inline Tags

   • Overview of block and inline JSDoc tags.

7. About JSDoc Plugins

   • How to create and use JSDoc plugins.

8. Using the Markdown Plugin

   • Enable Markdown support in JSDoc.

9. Tutorials

   • Adding tutorials to your API documentation.

10. Including a Package File

    • How to show package details in your documentation.

11. Including a README File

    • How to include a README file in your documentation.

12. License

    • License information for JSDoc.

Additional Resources:

1. JSDoc GitHub Repository

   • The official repository for JSDoc.

2. Apache License, Version 2.0

   • License information for JSDoc.

3. Third-Party Software Licenses

   • See LICENSE.md in the JSDoc GitHub Repository for details on third-party software licenses.

Feel free to adjust the links if necessary or let me know if there's anything else you need!