Coding: JSDoc Tags for API and Declarations

General rules:

• Descriptions should always start in a new line after the tag.
• @apioption and @optionparent need to be the last API Options tag.
• @apioption doclets without following code have to come before doclets with code. Closing parentheses do not count as code.
• API options should be exclusively defined in …Defaults.ts files.
• API interfaces should be defined in the class file referencing it.
• API class references must not be defined in …Defaults.ts files.

Symbols represents the scope the tag is used for:

• 🟪: API class reference / TypeScript declarations
• 🟡: API options / TypeScript declarations

JSDoc Tags

Tag	🟪	🟡	Description
@class	🟪		Adds a constructor to the class pattern.
@default		🟡	Expects a default value. Optionally can come first product keys in curly brackets {…} separated by the pipe character |, to limit the default value to specific products.
@deprecated	🟪	🟡	Needs a version value to be included in TypeScript declarations.
@function	🟪		Defines the namespace of the trailing function.
@ignore	🟪		Skips processing of the comment block.
@name	🟪		Defines a member of a namespace, usually a class or an interface.
@param	🟪		Defines a parameter for the constructor or function. Expects the type or the type union in curly brackets {…}, followed by the parameter name and a description.
@private	🟪	🟡	When combining API Declarations and API Options, use after @apioption/@optionparent to avoid options exposure in class reference.
@readonly	🟪		Marks an element as readonly, so that users get an error in TypeScript when trying to change it. This does not make an element readonly for real, just indicates the intention of usage.
@requires	🟪	🟡	Lists a path to a module to make it work. For official public elements this the path in code.highcharts.com. For internal elements this is the path in the /ts folder.
@return	🟪		Expects the type or the type union in curly brackets {…}, followed by a description.
@see	🟪	🟡	Define a markdown link to some other element. Expects the URL hash with the element path.
@since	🟪	🟡	Expects a version value to indicate the first appearance of an element in the public API. For option the version gets otherwise inherited from the parent option node.
@throws	🟪		Define an Error thrown by the function. See the JSDoc documentation.
@todo	🟪	🟡	An official note of necessary changes to a documented element.
@type	🟪	🟡	Expects the type or the type union in curly brackets {…}.

Custom Tags

Tag	🟪	🟡	Description
@apioption		🟡	Defines an option with the given name path. This tag has to be the last API option tag in a doclet!
@declare		🟡	TypeScript only. Moves the type in declarations to an alias or interface with the given namespace and name.
@exclude		🟡	List of properties from @extends sources to not be included, separated by space.
@extends		🟡	List of name paths to copy properties from, separated by komma character ,. Some property tags will not be copied like @default.
@ignore-option		🟡	This will prevent an option from be picked up in API options.
@optionparent		🟡	The properties of the following object get assigned to the given name path. This tag has to be the last API option tag in a doclet!
@product	🟪	🟡	Product keys (as in api.highcharts.com/…/ separated by spaces. As default options get assigned to all products.
@productdesc		🟡	Adds a product-specific description. First comes the product keys in curly brackets {…} separated by the pipe character |, followed by the description to add.
@sample		🟡	First comes the product keys in curly brackets {…} separated by the pipe character |. Second comes the path to the demo inside the /sample folder. Third comes the description of the demo.