From 2079c84165e467c79e2373f487069078fdbbe089 Mon Sep 17 00:00:00 2001 From: Tierney Cyren Date: Fri, 8 Apr 2022 15:01:04 -0400 Subject: [PATCH 1/5] doc: update styleguide Signed-off-by: Tierney Cyren --- doc/README.md | 318 +++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 264 insertions(+), 54 deletions(-) diff --git a/doc/README.md b/doc/README.md index 3d8ad6246839e6..42a52fe9093df8 100644 --- a/doc/README.md +++ b/doc/README.md @@ -8,38 +8,23 @@ formatting. You do not need to learn the entire style guide before contributing to documentation. Someone can always edit your material later to conform with this guide. -* Documentation is in markdown files with names formatted as - `lowercase-with-dashes.md`. - * Use an underscore in the filename only if the underscore is part of the - topic name (e.g., `child_process`). - * Some files, such as top-level markdown files, are exceptions. -* Documents should be word-wrapped at 80 characters. -* `.editorconfig` describes the preferred formatting. - * A [plugin][] is available for some editors to apply these rules. -* Check changes to documentation with `make test-doc -j` or `vcbuild test-doc`. -* [Use US spelling][]. -* [Use serial commas][]. -* Avoid first-person pronouns (_I_, _we_). - * Exception: _we recommend foo_ is preferable to _foo is recommended_. -* Use gender-neutral pronouns and gender-neutral plural nouns. - * OK: _they_, _their_, _them_, _folks_, _people_, _developers_ - * NOT OK: _his_, _hers_, _him_, _her_, _guys_, _dudes_ -* When combining wrapping elements (parentheses and quotes), place terminal - punctuation: - * Inside the wrapping element if the wrapping element contains a complete - clause. - * Outside of the wrapping element if the wrapping element contains only a - fragment of a clause. -* Documents must start with a level-one heading. +## Formatting and Structure + +### Headings + +* Each page must have a single `#`-level title at the top. +* Chapters in the same page must have `##`-level headings. +* Sub-chapters need to increase the number of `#` in the heading according to + their nesting depth. +* The page's title must follow [APA title case][title-case]. +* All chapters must follow [sentence case][sentence-style]. + +### Markdown Rules + * Prefer affixing links (`[a link][]`) to inlining links (`[a link](http://example.com)`). -* When documenting APIs, update the YAML comment associated with the API as - appropriate. This is especially true when introducing or deprecating an API. -* When documenting APIs, every function should have a usage example or - link to an example that uses the function. * For code blocks: * Use [language][]-aware fences. (\`\`\`js) - * For the [info string][], use one of the following. | Meaning | Info string | @@ -61,25 +46,39 @@ this guide. If one of your language-aware fences needs an info string that is not already on this list, you may use `text` until the grammar gets added to [`remark-preset-lint-node`][]. - * Code need not be complete. Treat code blocks as an illustration or aid to your point, not as complete running programs. If a complete running program is necessary, include it as an asset in `assets/code-examples` and link to it. -* When using underscores, asterisks, and backticks, please use - backslash-escaping: `\_`, `\*`, and ``\` ``. + * When using underscores, asterisks, and backticks, please use + backslash-escaping: `\_`, `\*`, and ``\` ``. + * No nesting lists more than 2 levels (due to the markdown renderer). + * For unordered lists, use asterisks instead of dashes. + +### Document Rules + +* Documentation is in markdown files with names formatted as + `lowercase-with-dashes.md`. + * Use an underscore in the filename only if the underscore is part of the + topic name (e.g., `child_process`). + * Some files, such as top-level markdown files, are exceptions. +* Documents should be word-wrapped at 80 characters. + +## Language + +### Spelling, Punctuation, Naming, and Referencing Rules + +* [Be direct][]. +* [Use US spelling][]. +* [Use serial commas][]. +* Avoid first-person pronouns (_I_, _we_). + * Exception: _we recommend foo_ is preferable to _foo is recommended_. +* Use gender-neutral pronouns and gender-neutral plural nouns. + * OK: _they_, _their_, _them_, _folks_, _people_, _developers_ + * NOT OK: _his_, _hers_, _him_, _her_, _guys_, _dudes_ * Constructors should use PascalCase. * Instances should use camelCase. * Denote methods with parentheses: `socket.end()` instead of `socket.end`. -* Function arguments or object properties should use the following format: - * ``* `name` {type|type2} Optional description. **Default:** `value`.`` - - * For example: \* `byteOffset` {integer} Index of first byte to expose. **Default:** `0`. - - * The `type` should refer to a Node.js type or a [JavaScript type][]. -* Function returns should use the following format: - * \* Returns: {type|type2} Optional description. - * E.g. \* Returns: {AsyncHook} A reference to `asyncHook`. * Use official styling for capitalization in products and projects. * OK: JavaScript, Google's V8 @@ -87,31 +86,242 @@ this guide. * Use _Node.js_ and not _Node_, _NodeJS_, or similar variants. * When referring to the executable, _`node`_ is acceptable. -* [Be direct][]. - +## Additional Context and Rules -* When referring to a version of Node.js in prose, use _Node.js_ and the version - number. Do not prefix the version number with _v_ in prose. This is to avoid - confusion about whether _v8_ refers to Node.js 8.x or the V8 JavaScript - engine. - - * OK: _Node.js 14.x_, _Node.js 14.3.1_ - * NOT OK: _Node.js v14_ -* [Use sentence-style capitalization for headings][]. +* `.editorconfig` describes the preferred formatting. + * A [plugin][] is available for some editors to apply these rules. +* Check changes to documentation with `make test-doc -j` or `vcbuild test-doc`. +* When combining wrapping elements (parentheses and quotes), place terminal + punctuation: + * Inside the wrapping element if the wrapping element contains a complete + clause. + * Outside of the wrapping element if the wrapping element contains only a + fragment of a clause. +* When documenting APIs, update the YAML comment associated with the API as + appropriate. This is especially true when introducing or deprecating an API. +* When documenting APIs, every function should have a usage example or + link to an example that uses the function. + +## API References + +The following rules only apply to the documentation of APIs. + +### Title and description + +Each module's API doc must use the actual object name returned by requiring it +as its title (such as `path`, `fs`, and `querystring`). + +Directly under the page title, add a one-line description of the module +as a markdown quote (beginning with `>`). + +Using the `querystring` module as an example: + +```markdown +# querystring + +> Utilities for parsing and formatting URL query strings. +``` + +### Module methods and events + +For modules that are not classes, their methods and events must be listed under +the `## Methods` and `## Events` chapters. + +Using `fs` as an example: + +```markdown +# fs + +## Events + +### Event: 'close' + +## Methods + +### `fs.access(path[, mode], callback)` +``` + +### Methods and their arguments + +The methods chapter must be in the following form: + +```markdown +### `objectName.methodName(required[, optional]))` + +* `required` string - A parameter description. +* `optional` Integer (optional) - Another parameter description. + +... +``` + +#### Function signature + +For modules, the `objectName` is the module's name. For classes, it must be the +name of the instance of the class, and must not be the same as the module's +name. + +Optional arguments are notated by square brackets `[]` surrounding the optional +argument as well as the comma required if this optional argument follows +another argument: + +```markdown +required[, optional] +``` + +#### Heading level + +The heading can be `###` or `####`-levels depending on whether the method +belongs to a module or a class. + +### Classes + +* API classes or classes that are part of modules must be listed under a + `## Class: TheClassName` chapter. +* One page can have multiple classes. +* Constructors must be listed with `###`-level headings. +* [Static Methods](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes/static) + must be listed under a `### Static Methods` chapter. +* [Instance Methods](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes#Prototype_methods) + must be listed under an `### Instance Methods` chapter. +* All methods that have a return value must start their description with + ``Returns `[TYPE]` - (Return description)`` + * If the method returns an `Object`, its structure can be specified + using a colon followed by a newline then an unordered list of properties in + the same style as function parameters. +* Instance Events must be listed under an `### Instance Events` chapter. +* Instance Properties must be listed under an `### Instance Properties` chapter. + * Instance Properties must start with `A [Property Type] ...` + +Using the `v8` classes as an example of some of the outlined structure: + +```markdown +# `v8` + +## Methods + +### `v8.cachedDataVersionTag()` + +## Class: Serializer + +### Instance Methods + +#### `serializer.writeHeader()` + +## Class: Deserializer + +### Instance Methods + +#### `deserializer.readHeader()` + +... +``` + +### Methods and their arguments + +The methods chapter must be in the following form: + +```markdown +### `objectName.methodName(required[, optional]))` + +* `required` string - A parameter description. +* `optional` Integer (optional) - Another parameter description. + +... +``` + +#### Heading level + +The heading can be `###` or `####`-levels depending on whether the method +belongs to a module or a class. + +#### Function signature + +For modules, the `objectName` is the module's name. For classes, it must be the +name of the instance of the class, and must not be the same as the module's +name. + +Optional arguments are notated by square brackets `[]` surrounding the optional +argument as well as the comma required if this optional argument follows +another argument: + +```markdown +required[, optional] +``` + +#### Argument descriptions + +More detailed information on each of the arguments is noted in an unordered list +below the method. The type of argument is notated by either JavaScript +primitives (e.g. `string`, `Promise`, or `Object`), a custom API structure, +or the wildcard `any`. + +If the argument is of type `Array`, use `[]` shorthand with the type of value +inside the array (for example,`any[]` or `string[]`). + +If the argument is of type `Promise`, parametrize the type with what the promise +resolves to (for example, `Promise` or `Promise`). + +If an argument can be of multiple types, separate the types with `|`. + +The description for `Function` type arguments should make it clear how it may be +called and list the types of the parameters that will be passed to it. + +#### Platform-specific functionality + +If an argument or a method is unique to certain platforms, those platforms are +denoted using a space-delimited italicized list following the datatype. Values +can be `macOS`, `Windows` or `Linux`. + +```markdown +* `path` boolean (optional) _macOS_ _Windows_ - the path to write a file to. +``` + +### Events + +The events chapter must be in following form: + +```markdown +#### Event: 'message' + +Returns: + +* `value` any - The transmitted value. + +... +``` + +The heading can be `###` or `####`-levels depending on whether the event +belongs to a module or a class. + +The arguments of an event follow the same rules as methods. + +### Properties + +The properties chapter must be in following form: + +```markdown +#### `port.close()` + +... +``` + +The heading can be `###` or `####`-levels depending on whether the property +belongs to a module or a class. -See also API documentation structure overview in [doctools README][]. +## See Also -For topics not covered here, refer to the [Microsoft Writing Style Guide][]. +* API documentation structure overview in [doctools README][]. +* [Microsoft Writing Style Guide][]. [Be direct]: https://docs.microsoft.com/en-us/style-guide/word-choice/use-simple-words-concise-sentences -[Javascript type]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Grammar_and_types#Data_structures_and_types [Microsoft Writing Style Guide]: https://docs.microsoft.com/en-us/style-guide/welcome/ [Use US spelling]: https://docs.microsoft.com/en-us/style-guide/word-choice/use-us-spelling-avoid-non-english-words -[Use sentence-style capitalization for headings]: https://docs.microsoft.com/en-us/style-guide/scannable-content/headings#formatting-headings [Use serial commas]: https://docs.microsoft.com/en-us/style-guide/punctuation/commas [`remark-preset-lint-node`]: https://github.com/nodejs/remark-preset-lint-node [doctools README]: ../tools/doc/README.md [info string]: https://github.github.com/gfm/#info-string [language]: https://github.com/highlightjs/highlight.js/blob/HEAD/SUPPORTED_LANGUAGES.md [plugin]: https://editorconfig.org/#download +[sentence-style]: https://docs.microsoft.com/en-us/style-guide/scannable-content/headings#formatting-headings +[title-case]: https://apastyle.apa.org/style-grammar-guidelines/capitalization/title-case From f5aee2a8fc9f4a6e24ec1b212ac9ee7886189994 Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Fri, 24 Jun 2022 06:28:22 -0700 Subject: [PATCH 2/5] fixup! doc: update styleguide --- doc/README.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/doc/README.md b/doc/README.md index 42a52fe9093df8..128289942a268d 100644 --- a/doc/README.md +++ b/doc/README.md @@ -8,7 +8,7 @@ formatting. You do not need to learn the entire style guide before contributing to documentation. Someone can always edit your material later to conform with this guide. -## Formatting and Structure +## Formatting and structure ### Headings @@ -19,7 +19,7 @@ this guide. * The page's title must follow [APA title case][title-case]. * All chapters must follow [sentence case][sentence-style]. -### Markdown Rules +### Markdown rules * Prefer affixing links (`[a link][]`) to inlining links (`[a link](http://example.com)`). @@ -55,7 +55,7 @@ this guide. * No nesting lists more than 2 levels (due to the markdown renderer). * For unordered lists, use asterisks instead of dashes. -### Document Rules +### Document rules * Documentation is in markdown files with names formatted as `lowercase-with-dashes.md`. @@ -66,7 +66,7 @@ this guide. ## Language -### Spelling, Punctuation, Naming, and Referencing Rules +### Spelling, punctuation, naming, and referencing rules * [Be direct][]. * [Use US spelling][]. @@ -87,7 +87,7 @@ this guide. * When referring to the executable, _`node`_ is acceptable. -## Additional Context and Rules +## Additional context and rules * `.editorconfig` describes the preferred formatting. * A [plugin][] is available for some editors to apply these rules. @@ -103,7 +103,7 @@ this guide. * When documenting APIs, every function should have a usage example or link to an example that uses the function. -## API References +## API references The following rules only apply to the documentation of APIs. @@ -204,13 +204,13 @@ Using the `v8` classes as an example of some of the outlined structure: ## Class: Serializer -### Instance Methods +### Instance methods #### `serializer.writeHeader()` ## Class: Deserializer -### Instance Methods +### Instance methods #### `deserializer.readHeader()` @@ -309,7 +309,7 @@ The properties chapter must be in following form: The heading can be `###` or `####`-levels depending on whether the property belongs to a module or a class. -## See Also +## See also * API documentation structure overview in [doctools README][]. * [Microsoft Writing Style Guide][]. From b14be6a0856f344d763a8bea054e33027f0a0e0f Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Fri, 24 Jun 2022 06:33:26 -0700 Subject: [PATCH 3/5] fixup! fixup! doc: update styleguide --- doc/README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/doc/README.md b/doc/README.md index 128289942a268d..90b37ad4228abb 100644 --- a/doc/README.md +++ b/doc/README.md @@ -52,7 +52,6 @@ this guide. it. * When using underscores, asterisks, and backticks, please use backslash-escaping: `\_`, `\*`, and ``\` ``. - * No nesting lists more than 2 levels (due to the markdown renderer). * For unordered lists, use asterisks instead of dashes. ### Document rules From 90df835b5ee517f0c4a87d32be75586790251e9b Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Fri, 24 Jun 2022 06:53:17 -0700 Subject: [PATCH 4/5] fixup! fixup! fixup! doc: update styleguide --- doc/README.md | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/doc/README.md b/doc/README.md index 90b37ad4228abb..38773e6ddc49da 100644 --- a/doc/README.md +++ b/doc/README.md @@ -12,12 +12,14 @@ this guide. ### Headings -* Each page must have a single `#`-level title at the top. -* Chapters in the same page must have `##`-level headings. -* Sub-chapters need to increase the number of `#` in the heading according to - their nesting depth. -* The page's title must follow [APA title case][title-case]. -* All chapters must follow [sentence case][sentence-style]. +* There must be exactly one `#` element at the start of each page containing + the title. +* All headings that are not the title must be a level 2 heading (`##`) or below. +* Nest headings semantically. For example, do not skip from level 2 (`##`) to + level 4 (`####`). +* Follow Microsoft's conventions for [formatting titles][] and + [formatting headers][]. This usually means using sentence-style + capitalization. ### Markdown rules @@ -319,8 +321,8 @@ belongs to a module or a class. [Use serial commas]: https://docs.microsoft.com/en-us/style-guide/punctuation/commas [`remark-preset-lint-node`]: https://github.com/nodejs/remark-preset-lint-node [doctools README]: ../tools/doc/README.md +[formatting headers]: https://docs.microsoft.com/en-us/style-guide/scannable-content/headings#formatting-headings +[formatting titles]: https://docs.microsoft.com/en-us/style-guide/text-formatting/formatting-titles [info string]: https://github.github.com/gfm/#info-string [language]: https://github.com/highlightjs/highlight.js/blob/HEAD/SUPPORTED_LANGUAGES.md [plugin]: https://editorconfig.org/#download -[sentence-style]: https://docs.microsoft.com/en-us/style-guide/scannable-content/headings#formatting-headings -[title-case]: https://apastyle.apa.org/style-grammar-guidelines/capitalization/title-case From 42483d75890a0ccf128b579e643b7df64300c442 Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Fri, 24 Jun 2022 06:54:17 -0700 Subject: [PATCH 5/5] fixup! fixup! fixup! fixup! doc: update styleguide --- doc/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/README.md b/doc/README.md index 38773e6ddc49da..2673ddf1d38248 100644 --- a/doc/README.md +++ b/doc/README.md @@ -127,7 +127,7 @@ Using the `querystring` module as an example: ### Module methods and events For modules that are not classes, their methods and events must be listed under -the `## Methods` and `## Events` chapters. +the `## Methods` and `## Events` headings. Using `fs` as an example: