website·Indexed 30 days ago
https://jsdoc3.vercel.app/Documentation for JSDoc, focusing on the tag dictionary and syntax for documenting JavaScript code. Includes detailed guides on tags such as @typedef, @type, @param, @returns, @module, and @class, as well as instructions for documenting CommonJS and AMD modules.
@file and can be used interchangeably to provide a file-level description: @fileoverview and @overview.@copyright tag is used to specify copyright information within a file overview comment. It is intended to be used in combination with the @file tag to provide a complete header for the source file./**
* @file This is my cool script.
* @copyright Michael Mathews 2011
*/@summary tag allows you to provide a short, concise version of a doclet's description. This is useful when the main description is long or verbose, as it provides a quick overview of the entity's purpose. The @summary tag can be added to any doclet./**
* A very long, verbose, wordy, long-winded, tedious, verbacious, tautological,
* profuse, expansive, enthusiastic, redundant, flowery, eloquent, articulate,
* loquacious, garrulous, chatty, extended, babbling description.
* @summary A concise summary.
*/
function bloviate() {}The @external tag identifies a class, namespace, or module defined outside of the current package. This allows you to document extensions to external symbols or provide information about them to users. When referring to an external symbol in other JSDoc tags (like @link or @augments), you must use the external: prefix (e.g., external:Foo), although the prefix is omitted within the @external tag itself.
Constraint: Only apply the @external tag to the highest-level symbol defined outside your project. For nested symbols, use @memberof external:ParentName instead of applying @external to the child.
/**
* The built in string object.
* @external String
* @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String|String}
*/@) provide structured information about the code. Common tags include @constructor to identify a class constructor and @param to define method parameters, including their type and description./**
* Represents a book.
* @constructor
* @param {string} title - The title of the book.
* @param {string} author - The author of the book.
*/
function Book(title, author) {}JSDoc uses block tags (starting with @) to provide structured metadata about JavaScript code. Common tags include:
@class (constructor), @function (method), @async (asynchronous function), @generator (generator function), @returns (return value), @param (function parameter), @throws (errors thrown).@public, @private, @protected, @package (package-private), @ignore (omit from docs).@augments (inherits from), @implements (implements interface), @inheritdoc (inherit parent docs), @override (overrides parent).@typedef (custom type), @type (object type), @enum (related properties), @interface (interface definition).@description (detailed description), @summary (short description), @example (usage example), @since (version added), @deprecated (no longer preferred), @author (author identity), @license (license info).@module (JS module), @namespace (namespace object), @file (file overview), @memberof (parent symbol).@) and must be followed by a line break, except when the tag is the final element in the JSDoc comment./**
* 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) {
// ...
}<caption></caption> element immediately after the @example tag. This allows you to label specific examples within a doclet./**
* Solves equations of the form a * x = b
* @example <caption>Example usage of method1.</caption>
* // returns 2
* globalNS.method1(5, 10);
* @returns {Number} Returns the value of x for the equation.
*/
globalNS.method1 = function (a, b) {
return b / a
}JSDoc allows you to incorporate a Markdown README file to serve as the home page (index.html) of your generated documentation. There are two methods to achieve this:
README.md directly in the list of source paths passed to the JSDoc CLI. JSDoc will use the first README.md it encounters.-R or --readme flag to specify a path to a README file. This file can have any name or extension, provided it is in Markdown format. This method takes precedence over any README.md files found in source paths.This functionality is available in JSDoc 3.3.0 and later when using the default template.
# Method 1: Including README.md in source paths
jsdoc path/to/js path/to/readme/README.md
# Method 2: Using the --readme option (takes precedence)
jsdoc --readme path/to/readme/README path/to/js@module tag in a standalone JSDoc comment. The value of the tag should be the module identifier used in the require() function. If the tag is used without a value, JSDoc attempts to guess the identifier based on the file path. When referencing a module from another comment using a namepath, prefix the identifier with module:. For example, a member of module my/pants would have a longname like module:my/pants.Jeans#hem./**
* Pants module.
* @module my/pants
* @see module:my/shirt
*/@callback tag is used to document the signature (parameters and return value) of a callback function that can be passed to other functions. Once defined, the callback's name acts as a custom type, allowing you to reference it in the @param tag of other functions to indicate that a parameter must be a function of that specific signature. You can use any tags typically associated with @method to further describe the callback./**
* This callback is defined as a global type.
* @callback requestCallback
* @param {number} responseCode
* @param {string} responseMessage
*/
/**
* Send a request.
* @param {requestCallback} cb - The callback that handles the response.
*/
Requester.prototype.send = function (cb) {
// code
};To document a symbol as an instance member of a class, use one of the following three patterns:
@memberof ClassName.prototype@memberof ClassName#@memberof ClassName in combination with the @instance tag./** @class Observable */
create('Observable', {
/** @memberof Observable.prototype */
publish: function (msg) {},
/** @memberof Observable# */
save: function () {},
/**
* @memberof Observable
* @instance
*/
end: function () {},
})