2019-06-21 21:19:21 +00:00
# Electron Documentation Style Guide
2015-08-22 12:07:45 +00:00
2016-06-24 19:28:41 +00:00
These are the guidelines for writing Electron documentation.
2015-08-22 12:07:45 +00:00
2016-06-24 01:45:37 +00:00
## Titles
2015-08-22 12:07:45 +00:00
2016-06-24 19:40:55 +00:00
* Each page must have a single `#` -level title at the top.
* Chapters in the same page must have `##` -level titles.
2016-07-01 05:33:22 +00:00
* Sub-chapters need to increase the number of `#` in the title according to
their nesting depth.
* All words in the page's title must be capitalized, except for conjunctions
like "of" and "and" .
2016-06-24 19:40:55 +00:00
* Only the first word of a chapter title must be capitalized.
2016-06-24 01:45:37 +00:00
Using `Quick Start` as example:
```markdown
# Quick Start
...
## Main process
...
## Renderer process
...
## Run your app
2015-08-22 12:07:45 +00:00
2016-06-24 01:45:37 +00:00
...
### Run as a distribution
...
### Manually downloaded Electron binary
...
```
For API references, there are exceptions to this rule.
## Markdown rules
2017-11-24 10:13:57 +00:00
* Use `sh` instead of `cmd` in code blocks (due to the syntax highlighter).
2016-06-24 19:28:41 +00:00
* Lines should be wrapped at 80 columns.
* No nesting lists more than 2 levels (due to the markdown renderer).
2016-08-16 21:07:50 +00:00
* All `js` and `javascript` code blocks are linted with
2020-11-02 09:58:14 +00:00
[standard-markdown ](https://www.npmjs.com/package/standard-markdown ).
2015-09-09 20:33:11 +00:00
2016-06-24 01:45:37 +00:00
## Picking words
2015-09-09 20:33:11 +00:00
2016-06-24 01:45:37 +00:00
* Use "will" over "would" when describing outcomes.
* Prefer "in the ___ process" over "on".
2015-09-09 20:33:11 +00:00
2016-06-24 01:45:37 +00:00
## API references
2015-09-09 20:33:11 +00:00
2016-06-24 19:28:41 +00:00
The following rules only apply to the documentation of APIs.
2015-08-22 12:07:45 +00:00
2016-06-24 01:45:37 +00:00
### Page title
2015-08-22 12:07:45 +00:00
2016-06-24 01:45:37 +00:00
Each page must use the actual object name returned by `require('electron')`
2016-06-24 19:40:55 +00:00
as the title, such as `BrowserWindow` , `autoUpdater` , and `session` .
2016-06-24 01:45:37 +00:00
2017-11-17 20:14:33 +00:00
Under the page title must be a one-line description starting with `>` .
2015-08-22 12:07:45 +00:00
2016-06-24 01:45:37 +00:00
Using `session` as example:
```markdown
# session
> Manage browser sessions, cookies, cache, proxy settings, etc.
2016-06-17 19:26:08 +00:00
```
2015-08-22 12:07:45 +00:00
2016-06-24 01:45:37 +00:00
### Module methods and events
For modules that are not classes, their methods and events must be listed under
2016-06-24 19:40:55 +00:00
the `## Methods` and `## Events` chapters.
2016-06-24 01:45:37 +00:00
2016-06-24 19:28:41 +00:00
Using `autoUpdater` as an example:
2016-06-24 01:45:37 +00:00
```markdown
# autoUpdater
## Events
### Event: 'error'
## Methods
### `autoUpdater.setFeedURL(url[, requestHeaders])`
2016-06-17 19:26:08 +00:00
```
2015-08-22 12:07:45 +00:00
2016-06-24 01:45:37 +00:00
### Classes
2016-07-01 05:30:55 +00:00
* API classes or classes that are part of modules must be listed under a
2016-06-24 19:40:55 +00:00
`## Class: TheClassName` chapter.
2016-07-01 05:30:55 +00:00
* One page can have multiple classes.
2016-07-13 05:00:28 +00:00
* Constructors must be listed with `###` -level titles.
* [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.
2016-09-24 23:59:30 +00:00
* All methods that have a return value must start their description with "Returns `[TYPE]` - Return description"
2016-09-27 04:04:54 +00:00
* 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.
2016-07-13 05:00:28 +00:00
* Instance Events must be listed under an `### Instance Events` chapter.
* Instance Properties must be listed under an `### Instance Properties` chapter.
2016-09-25 00:04:10 +00:00
* Instance properties must start with "A [Property Type] ..."
2016-06-24 01:45:37 +00:00
2016-06-24 19:40:55 +00:00
Using the `Session` and `Cookies` classes as an example:
2016-06-24 01:45:37 +00:00
```markdown
# session
## Methods
### session.fromPartition(partition)
2019-07-15 17:15:32 +00:00
## Static Properties
2016-06-24 01:45:37 +00:00
### session.defaultSession
## Class: Session
### Instance Events
#### Event: 'will-download'
### Instance Methods
2019-03-08 22:42:03 +00:00
#### `ses.getCacheSize()`
2016-06-24 01:45:37 +00:00
### Instance Properties
#### `ses.cookies`
## Class: Cookies
### Instance Methods
#### `cookies.get(filter, callback)`
```
### Methods
2016-06-24 19:28:41 +00:00
The methods chapter must be in the following form:
2016-06-24 01:45:37 +00:00
```markdown
### `objectName.methodName(required[, optional]))`
2016-12-29 22:11:26 +00:00
* `required` String - A parameter description.
* `optional` Integer (optional) - Another parameter description.
2016-06-24 01:45:37 +00:00
...
```
The title can be `###` or `####` -levels depending on whether it is a method of
2016-06-24 19:28:41 +00:00
a module or a class.
2016-06-24 01:45:37 +00:00
2016-06-24 22:59:30 +00:00
For modules, the `objectName` is the module's name. For classes, it must be the
2016-06-24 19:28:41 +00:00
name of the instance of the class, and must not be the same as the module's
name.
2016-06-24 01:45:37 +00:00
2016-06-24 19:28:41 +00:00
For example, the methods of the `Session` class under the `session` module must
use `ses` as the `objectName` .
2016-06-24 01:45:37 +00:00
2016-06-24 22:59:30 +00:00
The optional arguments are notated by square brackets `[]` surrounding the optional argument
2016-06-24 01:45:37 +00:00
as well as the comma required if this optional argument follows another
2016-06-24 22:59:30 +00:00
argument:
2017-11-20 06:18:24 +00:00
```sh
2016-06-24 22:59:30 +00:00
required[, optional]
```
2015-08-22 12:07:45 +00:00
2015-08-24 12:38:29 +00:00
Below the method is more detailed information on each of the arguments. The type
2015-10-09 06:19:16 +00:00
of argument is notated by either the common types:
2016-06-24 19:28:41 +00:00
2016-07-01 05:30:55 +00:00
* [`String` ](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String )
* [`Number` ](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number )
* [`Object` ](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object )
* [`Array` ](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array )
* [`Boolean` ](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean )
2016-09-25 07:13:34 +00:00
* Or a custom type like Electron's [`WebContent` ](api/web-contents.md )
2015-08-22 12:07:45 +00:00
2016-06-24 01:45:37 +00:00
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
2018-05-12 08:12:28 +00:00
can be `macOS` , `Windows` or `Linux` .
2016-06-17 19:33:50 +00:00
2016-06-24 19:28:41 +00:00
```markdown
2016-12-29 22:11:26 +00:00
* `animate` Boolean (optional) _macOS_ _Windows_ - Animate the thing.
2016-06-17 19:33:50 +00:00
```
2016-06-24 22:59:30 +00:00
`Array` type arguments must specify what elements the array may include in
2016-06-24 19:40:55 +00:00
the description below.
2016-06-24 01:45:37 +00:00
2016-06-24 19:40:55 +00:00
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.
2016-06-24 01:45:37 +00:00
2015-08-22 12:07:45 +00:00
### Events
2016-06-24 19:28:41 +00:00
The events chapter must be in following form:
2015-08-22 12:07:45 +00:00
2016-06-24 01:45:37 +00:00
```markdown
### Event: 'wake-up'
2015-08-22 12:07:45 +00:00
Returns:
* `time` String
2016-06-24 01:45:37 +00:00
...
2016-06-17 19:26:08 +00:00
```
2015-08-22 12:07:45 +00:00
2016-06-24 01:45:37 +00:00
The title can be `###` or `####` -levels depending on whether it is an event of
2016-06-24 19:28:41 +00:00
a module or a class.
2016-06-24 01:45:37 +00:00
2016-06-24 19:40:55 +00:00
The arguments of an event follow the same rules as methods.
2016-06-24 01:45:37 +00:00
### Properties
2016-06-24 19:28:41 +00:00
The properties chapter must be in following form:
2016-06-24 01:45:37 +00:00
```markdown
### session.defaultSession
...
2015-08-22 12:07:45 +00:00
```
2016-06-24 01:45:37 +00:00
The title can be `###` or `####` -levels depending on whether it is a property of
2016-06-24 19:28:41 +00:00
a module or a class.
2016-06-24 01:45:37 +00:00
## Documentation Translations
2018-03-02 20:05:49 +00:00
See [electron/i18n ](https://github.com/electron/i18n#readme )