From 076a34829bee40e35e4cfd0b335a6987bbbc84d0 Mon Sep 17 00:00:00 2001 From: jrfnl Date: Mon, 2 May 2022 09:43:37 +0200 Subject: [PATCH] JS Docs: convert from HTML to markdown Includes: * Removing stray unicode artifacts. * Improving formatting consistency in a couple of places. I.e. having "Good"/"Bad" both wrapped in emphasis, having the `:` in lists not included in the bold tags, refering to the correct tags in some examples - most for `@deprecated`. * Being more liberal with backticks around documentation `@tags`, like in the tables. * Improving accessibility by not using "here" as link text. * Removing trailing spaces. **Notes**: * The formatting around the `[tip]` should be double-checked as I'm not sure if the shortcode doesn't break now the contents is reformatted. * There are a few "inline headers" (using `**` not `##..`) in the "Formatting Guidelines" section, about which I wonder if those shouldn't be changed to proper headers. See: https://developer.wordpress.org/coding-standards/inline-documentation-standards/javascript/#formatting-guidelines Also note that while I haven't really "read" the document, only scanned it, I did get the impression that there was quite a lot of redundancy/duplication in the text. MIght be something to have a look at/iterate on in a follow-up PR. --- inline-documentation-standards/javascript.md | 676 ++++++------------- 1 file changed, 223 insertions(+), 453 deletions(-) diff --git a/inline-documentation-standards/javascript.md b/inline-documentation-standards/javascript.md index 7a792ad..50dd449 100644 --- a/inline-documentation-standards/javascript.md +++ b/inline-documentation-standards/javascript.md @@ -1,63 +1,76 @@ # JavaScript Documentation Standards -WordPress follows the JSDoc 3 standard for inline JavaScript documentation. -

What Should Be Documented

+WordPress follows the [JSDoc 3 standard](http://jsdoc.app/) for inline JavaScript documentation. + +## What Should Be Documented + JavaScript documentation in WordPress takes the form of either formatted blocks of documentation or inline comments. The following is a list of what should be documented in WordPress JavaScript files: - -

Documenting Tips

-

Language

-Short descriptions should be clear, simple, and brief. Document "what" and "when" – "why" should rarely need to be included. The "why" can go in the long description if needed. For example: - -Functions and closures are third-person singular elements, meaning third-person singular verbs should be used to describe what each does. - -[tip]Need help remembering how to conjugate for third-person singular verbs? Imagine prefixing the function, hook, class, or method summary with "It": - + +- Functions and class methods +- Objects +- Closures +- Object properties +- Requires +- Events +- File headers + +## Documenting Tips + +### Language + +Short descriptions should be clear, simple, and brief. Document "what" and "when" - "why" should rarely need to be included. The "why" can go in the long description if needed. For example: + +Functions and closures are _third-person singular_ elements, meaning _third-person singular verbs_ should be used to describe what each does. + +[tip] +Need help remembering how to conjugate for third-person singular verbs? Imagine prefixing the function, hook, class, or method summary with "It": + +- _Good_: "(It) Does something." +- _Bad:_ "(It) Do something." + [/tip] -Functions: What does the function do? - -@since: The recommended tool to use when searching for the version something was added to WordPress is svn blame. +**Functions**: What does the function do? -If, after using these tools, the version number cannot be determined, use @since Unknown. +- _Good_: Handles a click on X element. +- _Bad_: Included for back-compat for X element. + +**`@since`**: The recommended tool to use when searching for the version something was added to WordPress is [`svn blame`](https://make.wordpress.org/core/handbook/svn/code-history/#using-subversion-annotate). + +If, after using these tools, the version number cannot be determined, use `@since Unknown`. + +**Code Refactoring**: Do not refactor code in the file when changes to the documentation. + +### Grammar -Code Refactoring: Do not refactor code in the file when changes to the documentation. -

Grammar

Descriptive elements should be written as complete sentences. The one exception to this standard is file header summaries, which are intended as file "titles" more than sentences. The serial (Oxford) comma should be used when listing elements in summaries, descriptions, and parameter or return descriptions. -

Formatting Guidelines

+ +## Formatting Guidelines + The following guidelines should be followed to ensure that the content of the doc blocks can be parsed properly for inclusion in the code reference. -Short descriptions: +**Short descriptions**: Short descriptions should be a single sentence and contain no markup of any kind. If the description refers to an HTML element or tag, then it should be written as "link tag", not "<a>". For example: "Fires when printing the link tag in the header". -Long descriptions: +**Long descriptions**: Markdown can be used, if needed, in a long description. -@param and @return tags: +**`@param` and `@return` tags**: No HTML or markdown is permitted in the descriptions for these tags. HTML elements and tags should be written as "audio element" or "link tag". -

Line wrapping

+ +### Line wrapping + DocBlock text should wrap to the next line after 80 characters of text. If the DocBlock itself is indented on the left 20 character positions, the wrap could occur at position 100, but should not extend beyond a total of 120 characters wide. -

Aligning comments

+ +### Aligning comments + Related comments should be spaced so that they align to make them more easily readable. For example: @@ -69,29 +82,29 @@ For example: */ ``` -

Functions

+## Functions + Functions should be formatted as follows: - + +- **Summary**: A brief, one line explanation of the purpose of the function. Use a period at the end. +- **Description**: A supplement to the summary, providing a more detailed description. Use a period at the end. +- **`@deprecated x.x.x`**: Only use for deprecated functions, and provide the version the function was deprecated which should always be 3-digit (e.g. `@deprecated 3.6.0`), and the function to use instead. +- **`@since x.x.x`**: Should be 3-digit for initial introduction (e.g. `@since 3.6.0`). If significant changes are made, additional `@since` tags, versions, and descriptions should be added to serve as a changelog. +- **`@access`**: Only use for functions if private. If the function is private, it is intended for internal use only, and there will be no documentation for it in the code reference. +- **`@class`**: Use for class constructors. +- **`@augments`**: For class constuctors, list direct parents. +- **`@mixes`**: List mixins that are mixed into the object. +- **`@alias`**: If this function is first assigned to a temporary variable this allows you to change the name it's documented under. +- **`@memberof`**: Namespace that this function is contained within if JSDoc is unable to resolve this automatically. +- **`@static`**: For classes, used to mark that a function is a static method on the class constructor. +- **`@see`**: A function or class relied on. +- **`@link`**: URL that provides more information. +- **`@fires`**: Event fired by the function. Events tied to a specific class should list the class name. +- **`@listens`**: Events this function listens for. An event must be prefixed with the event namespace. Events tied to a specific class should list the class name. +- **`@global`**: Marks this function as a global function to be included in the global namespace. +- **`@param`**: Give a brief description of the variable; denote particulars (e.g. if the variable is optional, its default) with [JSDoc `@param` syntax](http://jsdoc.app/tags-param.html). Use a period at the end. +- **`@yield`**: For [generator functions](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function*), a description of the values expected to be yielded from this function. As with other descriptions, include a period at the end. +- **`@return`**: Note the period after the description. ```javascript /** @@ -106,7 +119,7 @@ Functions should be formatted as follows: * @class * @augments parent * @mixes mixin - * + * * @alias realName * @memberof namespace * @@ -131,34 +144,31 @@ Functions should be formatted as follows: */ ``` -

Backbone classes

-Backbone's extend calls should be formatted as follows: - -Backbone's initialize functions should be formatted as follows: - +## Backbone classes + +Backbone's `extend` calls should be formatted as follows: + +- **`@lends`** This tag will allow JSDoc to recognize the `extend` function from Backbone as a class definition. This should be placed right before the Object that contains the class definition. + +Backbone's `initialize` functions should be formatted as follows: + +- **Summary**: A brief, one line explanation of the purpose of the function. Use a period at the end. +- **Description**: A supplement to the summary, providing a more detailed description. Use a period at the end. +- **`@deprecated x.x.x`**: Only use for deprecated classes, and provide the version the class was deprecated which should always be 3-digit (e.g. `@deprecated 3.6.0`), and the class to use instead. +- **`@since x.x.x`**: Should be 3-digit for initial introduction (e.g. `@since 3.6.0`). If significant changes are made, additional `@since` tags, versions, and descriptions should be added to serve as a changelog. +- **`@constructs`**: Marks this function as the constructor of this class. +- **`@augments`**: List direct parents. +- **`@mixes`**: List mixins that are mixed into the class. +- **`@requires`**: Lists modules that this class requires. Multiple `@requires` tags can be used. +- **`@alias`**: If this class is first assigned to a temporary variable this allows you to change the name it's documented under. +- **`@memberof`**: Namespace that this class is contained within if JSDoc is unable to resolve this automatically. +- **`@static`**: For classes, used to mark that a function is a static method on the class constructor. +- **`@see`**: A function or class relied on. +- **`@link`**: URL that provides more information. +- **`@fires`**: Event fired by the constructor. Should list the class name. +- **`@param`**: Document the arguments passed to the constructor even if not explicitly listed in `initialize`. Use a period at the end. + - Backbone Models are passed `attributes` and `options` parameters. + - Backbone Views are passed an `options` parameter. ```javascript Class = Parent.extend( /** @lends namespace.Class.prototype */{ @@ -193,7 +203,7 @@ Class = Parent.extend( /** @lends namespace.Class.prototype */{ } ); ``` -If a Backbone class does not have an initialize function it should be documented by using @inheritDoc as follows: +If a Backbone class does not have an initialize function it should be documented by using `@inheritDoc` as follows: ```javascript /** @@ -222,10 +232,12 @@ Class = Parent.extend( /** @lends namespace.Class.prototype */{ } ); ``` -
Note: This currently doesn't provide the expected functionality due to a bug with JSDoc's inheritDoc tag. See the issue here
-

Local functions

+> Note: This currently doesn't provide the expected functionality due to a bug with JSDoc's inheritDoc tag. See [JSDocs3 issue 1012](https://github.com/jsdoc3/jsdoc/issues/1012). + +## Local functions + At times functions will be assigned to a local variable before being assigned as a class member. -Such functions should be marked as inner functions of the namespace that uses them using ~. +Such functions should be marked as inner functions of the namespace that uses them using `~`. The functions should be formatted as follows: ```javascript @@ -259,20 +271,21 @@ Class = Parent.extend( /** @lends namespace.Class.prototype */{ } ); ``` -

Local ancestors

-At times classes will have Ancestors that are only assigned to a local variable. Such classes should be assigned to the namespace their children are and be made inner classes using ~. -These should be documented as follows: -

Class members

+## Local ancestors + +At times classes will have Ancestors that are only assigned to a local variable. Such classes should be assigned to the namespace their children are and be made inner classes using `~`. + +## Class members + Class members should be formatted as follows: - + +- **Short description**: Use a period at the end. +- **`@since x.x.x`**: Should be 3-digit for initial introduction (e.g. `@since 3.6.0`). If significant changes are made, additional `@since` tags, versions, and descriptions should be added to serve as a changelog. +- **`@access`**: If the members is private, protected or public. Private members are intended for internal use only. +- **`@type`**: List the type of the class member. +- **`@property`** List all properties this object has in case it's an Object. Use a period at the end. +- **`@member`**: Optionally use this to override JSDoc's member detection in place of `@type` to force a class member. +- **`@memberof`**: Optionally use this to override what class this is a member of. ```javascript /** @@ -289,15 +302,15 @@ Class members should be formatted as follows: */ ``` -

Namespaces

+## Namespaces + Namespaces should be formatted as follows: - + +- **Short description**: Use a period at the end. +- **`@namespace`**: Marks this symbol as a namespace, optionally provide a name as an override. +- **`@since x.x.x`**: Should be 3-digit for initial introduction (e.g. `@since 3.6.0`). If significant changes are made, additional `@since` tags, versions, and descriptions should be added to serve as a changelog. +- **`@memberof`**: Namespace that this namespace is contained in. +- **`@property`**: Properties that this namespace exposes. Use a period at the end. ```javascript /** @@ -312,15 +325,17 @@ Namespaces should be formatted as follows: */ ``` -

Inline Comments

+## Inline Comments + Inline comments inside methods and functions should be formatted as follows: -

Single line comments

+ +### Single line comments ```javascript // Extract the array values. ``` -

Multi-line comments

+### Multi-line comments ```javascript /* @@ -330,8 +345,10 @@ Inline comments inside methods and functions should be formatted as follows: */ ``` -Important note: Multi-line comments must not begin with /** (double asterisk). Use /* (single asterisk) instead. -

File Headers

+**Important note:** Multi-line comments must not begin with `/**` (double asterisk). Use `/*` (single asterisk) instead. + +## File Headers + The JSDoc file header block is used to give an overview of what is contained in the file. Whenever possible, all WordPress JavaScript files should contain a header block. @@ -349,341 +366,94 @@ WordPress uses JSHint for general code quality testing. Any inline configuration * @author AuthorName. * @since x.x.x */ - + /** jshint {inline configuration here} */ ``` -

Supported JSDoc Tags

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
TagDescription
@abstractThis method can be implemented (or overridden) by the inheritor.
@accessSpecify the access level of this member (private, public, or protected).
@aliasTreat a member as if it had a different name.
@augmentsThis class inherits from a parent class.
@authorIdentify the author of an item.
@borrowsThis object uses something from another object.
@callbackDocument a callback function.
@classThis function is a class constructor.
@classdescUse the following text to describe the entire class.
@constantDocument an object as a constant.
@constructsThis function member will be the constructor for the previous class.
@copyrightDocument some copyright information.
@defaultDocument the default value.
@deprecatedDocument that this is no longer the preferred way.
@descriptionDescribe a symbol.
@enumDocument a collection of related properties.
@eventDocument an event.
@exampleProvide an example of how to use a documented item.
@exportsIdentify the member that is exported by a JavaScript module.
@externalDocument an external class/namespace/module.
@fileDescribe a file.
@firesDescribe the events this method may fire.
@functionDescribe a function or method.
@globalDocument a global object.
@ignore[todo] Remove this from the final output.
@innerDocument an inner object.
@instanceDocument an instance member.
@kindWhat kind of symbol is this?
@lendsDocument properties on an object literal as if they belonged to a symbol with a given name.
@license[todo] Document the software license that applies to this code.
@linkInline tag - create a link.
@memberDocument a member.
@memberofThis symbol belongs to a parent symbol.
@mixesThis object mixes in all the members from another object.
@mixinDocument a mixin object.
@moduleDocument a JavaScript module.
@nameDocument the name of an object.
@namespaceDocument a namespace object.
@paramDocument the parameter to a function.
@privateThis symbol is meant to be private.
@propertyDocument a property of an object.
@protectedThis member is meant to be protected.
@publicThis symbol is meant to be public.
@readonlyThis symbol is meant to be read-only.
@requiresThis file requires a JavaScript module.
@returnDocument the return value of a function.
@seeRefer to some other documentation for more information.
@sinceDocuments the version at which the function was added, or when significant changes are made.
@staticDocument a static member.
@thisWhat does the 'this' keyword refer to here?
@throwsDescribe what errors could be thrown.
@todoDocument tasks to be completed.
@tutorialInsert a link to an included tutorial file.
@typeDocument the type of an object.
@typedefDocument a custom type.
@variationDistinguish different objects with the same name.
@versionDocuments the version number of an item.
@yieldDocument the yielded values of a generator function.
-

Unsupported JSDoc Tags

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
TagWhy it's not supported
@summaryShould not be used. See the example of how to separate a summary from the full description.
@virtualAn unsupported synonym. Use @abstract instead.
@extendsAn unsupported synonym. Use @augments instead.
@constructorAn unsupported synonym. Use @class instead.
@constAn unsupported synonym. Use @constant instead.
@defaultvalueAn unsupported synonym. Use @default instead.
@descAn unsupported synonym. Use @description instead.
@hostAn unsupported synonym. Use @external instead.
@fileoverviewAn unsupported synonym. Use @file instead.
@overviewAn unsupported synonym. Use @file instead.
@emitsAn unsupported synonym. Use @fires instead.
@funcAn unsupported synonym. Use @function instead.
@methodAn unsupported synonym. Use @function instead.
@varAn unsupported synonym. Use @member instead.
@emitsAn unsupported synonym. Use @fires instead.
@argAn unsupported synonym. Use @param instead.
@argumentAn unsupported synonym. Use @param instead.
@propAn unsupported synonym. Use @property instead.
@returnsAn unsupported synonym. Use @return instead.
@exceptionAn unsupported synonym. Use @throws instead.
+## Supported JSDoc Tags + +| Tag | Description | +|----------------|----------------------------------------------------------------------------------------------| +| `@abstract` | This method can be implemented (or overridden) by the inheritor. | +| `@access` | Specify the access level of this member (private, public, or protected). | +| `@alias` | Treat a member as if it had a different name. | +| `@augments` | This class inherits from a parent class. | +| `@author` | Identify the author of an item. | +| `@borrows` | This object uses something from another object. | +| `@callback` | Document a callback function. | +| `@class` | This function is a class constructor. | +| `@classdesc` | Use the following text to describe the entire class. | +| `@constant` | Document an object as a constant. | +| `@constructs` | This function member will be the constructor for the previous class. | +| `@copyright` | Document some copyright information. | +| `@default` | Document the default value. | +| `@deprecated` | Document that this is no longer the preferred way. | +| `@description` | Describe a symbol. | +| `@enum` | Document a collection of related properties. | +| `@event` | Document an event. | +| `@example` | Provide an example of how to use a documented item. | +| `@exports` | Identify the member that is exported by a JavaScript module. | +| `@external` | Document an external class/namespace/module. | +| `@file` | Describe a file. | +| `@fires` | Describe the events this method may fire. | +| `@function` | Describe a function or method. | +| `@global` | Document a global object. | +| `@ignore` | [todo] Remove this from the final output. | +| `@inner` | Document an inner object. | +| `@instance` | Document an instance member. | +| `@kind` | What kind of symbol is this? | +| `@lends` | Document properties on an object literal as if they belonged to a symbol with a given name. | +| `@license` | [todo] Document the software license that applies to this code. | +| `@link` | Inline tag - create a link. | +| `@member` | Document a member. | +| `@memberof` | This symbol belongs to a parent symbol. | +| `@mixes` | This object mixes in all the members from another object. | +| `@mixin` | Document a mixin object. | +| `@module` | Document a JavaScript module. | +| `@name` | Document the name of an object. | +| `@namespace` | Document a namespace object. | +| `@param` | Document the parameter to a function. | +| `@private` | This symbol is meant to be private. | +| `@property` | Document a property of an object. | +| `@protected` | This member is meant to be protected. | +| `@public` | This symbol is meant to be public. | +| `@readonly` | This symbol is meant to be read-only. | +| `@requires` | This file requires a JavaScript module. | +| `@return` | Document the return value of a function. | +| `@see` | Refer to some other documentation for more information. | +| `@since` | Documents the version at which the function was added, or when significant changes are made. | +| `@static` | Document a static member. | +| `@this` | What does the 'this' keyword refer to here? | +| `@throws` | Describe what errors could be thrown. | +| `@todo` | Document tasks to be completed. | +| `@tutorial` | Insert a link to an included tutorial file. | +| `@type` | Document the type of an object. | +| `@typedef` | Document a custom type. | +| `@variation` | Distinguish different objects with the same name. | +| `@version` | Documents the version number of an item. | +| `@yield` | Document the yielded values of a generator function. | + +## Unsupported JSDoc Tags + +| Tag | Why it's not supported | +|-----------------|-----------------------------------------------------------------------------------------------| +| `@summary` | Should not be used. See the example of how to separate a summary from the full description. | +| `@virtual` | An unsupported synonym. Use `@abstract` instead. | +| `@extends` | An unsupported synonym. Use `@augments` instead. | +| `@constructor` | An unsupported synonym. Use `@class` instead. | +| `@const` | An unsupported synonym. Use `@constant` instead. | +| `@defaultvalue` | An unsupported synonym. Use `@default` instead. | +| `@desc` | An unsupported synonym. Use `@description` instead. | +| `@host` | An unsupported synonym. Use `@external` instead. | +| `@fileoverview` | An unsupported synonym. Use `@file` instead. | +| `@overview` | An unsupported synonym. Use `@file` instead. | +| `@emits` | An unsupported synonym. Use `@fires` instead. | +| `@func` | An unsupported synonym. Use `@function` instead. | +| `@method` | An unsupported synonym. Use `@function` instead. | +| `@var` | An unsupported synonym. Use `@member` instead. | +| `@emits` | An unsupported synonym. Use `@fires` instead. | +| `@arg` | An unsupported synonym. Use `@param` instead. | +| `@argument` | An unsupported synonym. Use `@param` instead. | +| `@prop` | An unsupported synonym. Use `@property` instead. | +| `@returns` | An unsupported synonym. Use `@return` instead. | +| `@exception` | An unsupported synonym. Use `@throws` instead. |