electron/docs/styleguide.md

240 lines
5.6 KiB
Markdown
Raw Normal View History

2015-08-22 12:07:45 +00:00
# Electron Documentation Styleguide
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-06-24 22:59:30 +00:00
* Sub-chapters need to increase the number of `#` in the title according to their
2016-06-24 19:40:55 +00:00
nesting depth.
* All words in the page's title must be capitalized.
* 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
2016-06-24 19:28:41 +00:00
* Use `bash` instead of `cmd` in code blocks (due to the syntax highlighter).
* Lines should be wrapped at 80 columns.
* No nesting lists more than 2 levels (due to the markdown renderer).
2016-06-24 01:45:37 +00:00
## Picking words
2016-06-24 01:45:37 +00:00
* Use "will" over "would" when describing outcomes.
* Prefer "in the ___ process" over "on".
2016-06-24 01:45:37 +00:00
## API references
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
Under the page tile 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.
```
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])`
```
2015-08-22 12:07:45 +00:00
2016-06-24 01:45:37 +00:00
### Classes
* 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.
* One page can have multiple classes.
* The constructors must be listed with `###`-level titles.
* The methods must be listed under an `### Instance Methods` chapter.
* The events must be listed under an `### Instance Events` chapter.
* The properties must be listed under an `### Instance Properties` chapter.
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)
## Properties
### session.defaultSession
## Class: Session
### Instance Events
#### Event: 'will-download'
### Instance Methods
#### `ses.getCacheSize(callback)`
### 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]))`
* `required` String
* `optional` Integer (optional)
...
```
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:
```
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
of argument is notated by either the common types:
2016-06-24 19:28:41 +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)
* Or a custom type like Electron's [`WebContent`](api/web-content.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
can be `macOS`, `Windows`, or `Linux`.
2016-06-17 19:33:50 +00:00
2016-06-24 19:28:41 +00:00
```markdown
2016-06-22 06:02:01 +00:00
* `animate` Boolean (optional) _macOS_ _Windows_
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
...
```
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
Translations of the Electron docs are located within the `docs-translations`
directory.
To add another set (or partial set):
* Create a subdirectory named by language abbreviation.
* Translate the files.
* Update the `README.md` within your language directory to link to the files
you have translated.
* Add a link to your translation directory on the main Electron
[README](https://github.com/electron/electron#documentation-translations).
Note that the files under `docs-translations` must only include the translated
ones, the original English files should not be copied there.