docs: update style guide (#29029)

* clearer heading rules

* docs: clarify documentation style guide rules

* Update docs/styleguide.md

Co-authored-by: Mark Lee <malept@users.noreply.github.com>

* fixes

Co-authored-by: Mark Lee <malept@users.noreply.github.com>
This commit is contained in:
Erick Zhao 2021-05-18 19:55:36 -07:00 committed by GitHub
parent d518b6abc8
commit 6f9df7983d
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23

View file

@ -2,15 +2,14 @@
These are the guidelines for writing Electron documentation. These are the guidelines for writing Electron documentation.
## Titles ## Headings
* Each page must have a single `#`-level title at the top. * Each page must have a single `#`-level title at the top.
* Chapters in the same page must have `##`-level titles. * Chapters in the same page must have `##`-level headings.
* Sub-chapters need to increase the number of `#` in the title according to * Sub-chapters need to increase the number of `#` in the heading according to
their nesting depth. their nesting depth.
* All words in the page's title must be capitalized, except for conjunctions * The page's title must follow [APA title case][title-case].
like "of" and "and" . * All chapters must follow [APA sentence case][sentence-case].
* Only the first word of a chapter title must be capitalized.
Using `Quick Start` as example: Using `Quick Start` as example:
@ -44,12 +43,20 @@ For API references, there are exceptions to this rule.
## Markdown rules ## Markdown rules
This repository uses the [`markdownlint`][markdownlint] package to enforce consistent
Markdown styling. For the exact rules, see the `.markdownlint.json` file in the root
folder.
There are a few style guidelines that aren't covered by the linter rules:
<!--TODO(erickzhao): make sure this matches with the lint:markdownlint task-->
* Use `sh` instead of `cmd` in code blocks (due to the syntax highlighter). * Use `sh` instead of `cmd` in code blocks (due to the syntax highlighter).
* Lines should be wrapped at 80 columns. * Keep line lengths between 80 and 100 characters if possible for readability
purposes.
* No nesting lists more than 2 levels (due to the markdown renderer). * No nesting lists more than 2 levels (due to the markdown renderer).
* All `js` and `javascript` code blocks are linted with * All `js` and `javascript` code blocks are linted with
[standard-markdown](https://www.npmjs.com/package/standard-markdown). [standard-markdown](https://www.npmjs.com/package/standard-markdown).
* For unordered lists, use asterisks instead of dashes * For unordered lists, use asterisks instead of dashes.
## Picking words ## Picking words
@ -60,14 +67,15 @@ For API references, there are exceptions to this rule.
The following rules only apply to the documentation of APIs. The following rules only apply to the documentation of APIs.
### Page title ### Title and description
Each page must use the actual object name returned by `require('electron')` Each module's API doc must use the actual object name returned by `require('electron')`
as the title, such as `BrowserWindow`, `autoUpdater`, and `session`. as its title (such as `BrowserWindow`, `autoUpdater`, and `session`).
Under the page title must be a one-line description starting with `>`. Directly under the page title, add a one-line description of the module
as a markdown quote (beginning with `>`).
Using `session` as example: Using the `session` module as an example:
```markdown ```markdown
# session # session
@ -99,14 +107,19 @@ Using `autoUpdater` as an example:
* API classes or classes that are part of modules must be listed under a * API classes or classes that are part of modules must be listed under a
`## Class: TheClassName` chapter. `## Class: TheClassName` chapter.
* One page can have multiple classes. * One page can have multiple classes.
* Constructors must be listed with `###`-level titles. * 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. * [Static Methods](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes/static)
* [Instance Methods](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes#Prototype_methods) must be listed under an `### Instance Methods` chapter. must be listed under a `### Static Methods` chapter.
* All methods that have a return value must start their description with "Returns `[TYPE]` - Return description" * [Instance Methods](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes#Prototype_methods)
* 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. 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 Events must be listed under an `### Instance Events` chapter.
* Instance Properties must be listed under an `### Instance Properties` chapter. * Instance Properties must be listed under an `### Instance Properties` chapter.
* Instance properties must start with "A [Property Type] ..." * Instance Properties must start with "A [Property Type] ..."
Using the `Session` and `Cookies` classes as an example: Using the `Session` and `Cookies` classes as an example:
@ -142,7 +155,7 @@ Using the `Session` and `Cookies` classes as an example:
#### `cookies.get(filter, callback)` #### `cookies.get(filter, callback)`
``` ```
### Methods ### Methods and their arguments
The methods chapter must be in the following form: The methods chapter must be in the following form:
@ -155,8 +168,12 @@ The methods chapter must be in the following form:
... ...
``` ```
The title can be `###` or `####`-levels depending on whether it is a method of #### Heading level
a module or a class.
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 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 of the instance of the class, and must not be the same as the module's
@ -165,23 +182,33 @@ name.
For example, the methods of the `Session` class under the `session` module must For example, the methods of the `Session` class under the `session` module must
use `ses` as the `objectName`. use `ses` as the `objectName`.
The optional arguments are notated by square brackets `[]` surrounding the optional argument Optional arguments are notated by square brackets `[]` surrounding the optional
as well as the comma required if this optional argument follows another argument as well as the comma required if this optional argument follows another
argument: argument:
```sh ```markdown
required[, optional] required[, optional]
``` ```
Below the method is more detailed information on each of the arguments. The type #### Argument descriptions
of argument is notated by either the common types:
* [`String`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) More detailed information on each of the arguments is noted in an unordered list
* [`Number`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) below the method. The type of argument is notated by either JavaScript primitives
* [`Object`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) (e.g. `String`, `Promise`, or `Object`), a custom API structure like Electron's
* [`Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) [`Cookie`](api/structures/cookie.md), or the wildcard `any`.
* [`Boolean`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)
* Or a custom type like Electron's [`WebContent`](api/web-contents.md) 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<void>` or `Promise<String>`).
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 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 denoted using a space-delimited italicized list following the datatype. Values
@ -191,12 +218,6 @@ can be `macOS`, `Windows` or `Linux`.
* `animate` Boolean (optional) _macOS_ _Windows_ - Animate the thing. * `animate` Boolean (optional) _macOS_ _Windows_ - Animate the thing.
``` ```
`Array` type arguments must specify what elements the array may include in
the description below.
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.
### Events ### Events
The events chapter must be in following form: The events chapter must be in following form:
@ -211,8 +232,8 @@ Returns:
... ...
``` ```
The title can be `###` or `####`-levels depending on whether it is an event of The heading can be `###` or `####`-levels depending on whether the event
a module or a class. belongs to a module or a class.
The arguments of an event follow the same rules as methods. The arguments of an event follow the same rules as methods.
@ -226,9 +247,13 @@ The properties chapter must be in following form:
... ...
``` ```
The title can be `###` or `####`-levels depending on whether it is a property of The heading can be `###` or `####`-levels depending on whether the property
a module or a class. belongs to a module or a class.
## Documentation Translations ## Documentation translations
See [electron/i18n](https://github.com/electron/i18n#readme) See [electron/i18n](https://github.com/electron/i18n#readme)
[title-case]: https://apastyle.apa.org/style-grammar-guidelines/capitalization/title-case
[sentence-case]: https://apastyle.apa.org/style-grammar-guidelines/capitalization/sentence-case
[markdownlint]: https://github.com/DavidAnson/markdownlint