mirrors/electron
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Merge pull request #6216 from electron/class-docs

Browse source 
Add details to docs/styleguide.md
This commit is contained in:
Cheng Zhao 2016-07-01 05:34:01 +00:00 committed by GitHub
commit 36a0a491c9
1 changed files with 226 additions and 88 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

314
docs/styleguide.md
View file

@ -1,102 +1,240 @@
# Electron Documentation Styleguide
Find the appropriate section for your task: [reading Electron documentation](#reading-electron-documentation)
or [writing Electron documentation](#writing-electron-documentation).
These are the guidelines for writing Electron documentation.
## Writing Electron Documentation
## Titles
These are the ways that we construct the Electron documentation.
* Each page must have a single `#`-level title at the top.
* Chapters in the same page must have `##`-level titles.
* 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" .
* Only the first word of a chapter title must be capitalized.
- Maximum one `h1` title per page.
- Use `bash` instead of `cmd` in code blocks (because of syntax highlighter).
- Doc `h1` titles should match object name (i.e. `browser-window` →
`BrowserWindow`).
- Hyphen separated filenames, however, are fine.
- No headers following headers, add at least a one-sentence description.
- Methods headers are wrapped in `code` ticks.
- Event headers are wrapped in single 'quotation' marks.
- No nesting lists more than 2 levels (unfortunately because of markdown
renderer).
- Add section titles: Events, Class Methods and Instance Methods.
- Use 'will' over 'would' when describing outcomes.
- Events and methods are `h3` headers.
- Optional arguments written as `function (required[, optional])`.
- Optional arguments are denoted when called out in list.
- Line length is 80-column wrapped.
- Platform specific methods are noted in italics following method header.
- ```### `method(foo, bar)` _macOS_```
- Prefer 'in the ___ process' over 'on'
Using `Quick Start` as example:
### Documentation Translations
```markdown
# Quick Start
...
## Main process
...
## Renderer process
...
## Run your app
...
### Run as a distribution
...
### Manually downloaded Electron binary
...
```
For API references, there are exceptions to this rule.
## Markdown rules
* 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).
## Picking words
* Use "will" over "would" when describing outcomes.
* Prefer "in the ___ process" over "on".
## API references
The following rules only apply to the documentation of APIs.
### Page title
Each page must use the actual object name returned by `require('electron')`
as the title, such as `BrowserWindow`, `autoUpdater`, and `session`.
Under the page tile must be a one-line description starting with `>`.
Using `session` as example:
```markdown
# session
> Manage browser sessions, cookies, cache, proxy settings, etc.
```
### Module methods and events
For modules that are not classes, their methods and events must be listed under
the `## Methods` and `## Events` chapters.
Using `autoUpdater` as an example:
```markdown
# autoUpdater
## Events
### Event: 'error'
## Methods
### `autoUpdater.setFeedURL(url[, requestHeaders])`
```
### Classes
* API classes or classes that are part of modules must be listed under a
`## 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.
Using the `Session` and `Cookies` classes as an example:
```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
The methods chapter must be in the following form:
```markdown
### `objectName.methodName(required[, optional]))`
* `required` String
* `optional` Integer (optional)
...
```
The title can be `###` or `####`-levels depending on whether it is a method of
a module or a class.
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.
For example, the methods of the `Session` class under the `session` module must
use `ses` as the `objectName`.
The optional arguments are notated by square brackets `[]` surrounding the optional argument
as well as the comma required if this optional argument follows another
argument:
```
required[, optional]
```
Below the method is more detailed information on each of the arguments. The type
of argument is notated by either the common types:
* [`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)
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
* `animate` Boolean (optional) _macOS_ _Windows_
```
`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
The events chapter must be in following form:
```markdown
### Event: 'wake-up'
Returns:
* `time` String
...
```
The title can be `###` or `####`-levels depending on whether it is an event of
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
### session.defaultSession
...
```
The title can be `###` or `####`-levels depending on whether it is a property of
a module or a class.
## 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.
- Within that subdirectory, duplicate the `docs` directory, keeping the
names of directories and files same.
- Translate the files.
- Update the `README.md` within your language directory to link to the files
* 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).
* Add a link to your translation directory on the main Electron
[README](https://github.com/electron/electron#documentation-translations).
## Reading Electron Documentation
Here are some tips for understanding Electron documentation syntax.
### Methods
An example of [method](https://developer.mozilla.org/en-US/docs/Glossary/Method)
documentation:
```
`methodName(required[, optional]))`
* `required` String (**required**)
* `optional` Integer
```
The method name is followed by the arguments it takes. Optional arguments are
notated by brackets surrounding the optional argument as well as the comma
required if this optional argument follows another argument.
Below the method is more detailed information on each of the arguments. The type
of argument is notated by either the common types:
[`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)
or a custom type like Electron's [`webContent`](api/web-content.md).
If an argument 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`.
```
* `animate` Boolean (optional) _macOS_ _Windows_
```
### Events
An example of [event](https://developer.mozilla.org/en-US/docs/Web/API/Event)
documentation:
```
Event: 'wake-up'
Returns:
* `time` String
```
The event is a string that is used after a `.on` listener method. If it returns
a value it and its type is noted below. If you were to listen and respond to
this event it might look something like this:
```javascript
Alarm.on('wake-up', (time) => {
console.log(time)
})
```
Note that the files under `docs-translations` must only include the translated
ones, the original English files should not be copied there.