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

Add details to docs/styleguide.md

Browse source
This commit is contained in:
Cheng Zhao 2016-06-24 10:45:37 +09:00
parent 552c9b7f0a
commit 38592aaef7
1 changed files with 198 additions and 61 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

259
docs/styleguide.md
View file

@ -1,66 +1,169 @@
# Electron Documentation Styleguide
Find the appropriate section for your task: [reading Electron documentation](#reading-electron-documentation)
or [writing Electron documentation](#writing-electron-documentation).
## Writing Electron Documentation
These are the ways that we construct the Electron documentation.
- 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
## Titles
Each page has only one `#`-level title on the top, following chapters in the
same page must have `##`-level titles, and sub-chapters need to increase the
number of `#` in title according to its nesting depth.
For the page's title, all words must be capitalized, for other chapters, only
the first word has to be capitalized.
Using `Quick Start` as example:
```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 (because of syntax highlighter).
* Line length is 80-column wrapped.
* 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'
### Documentation Translations
## Picking words
Translations of the Electron docs are located within the `docs-translations`
directory.
* Use "will" over "would" when describing outcomes.
* Prefer "in the ___ process" over "on".
To add another set (or partial set):
## API references
- 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
you have translated.
- Add a link to your translation directory on the main Electron [README](https://github.com/electron/electron#documentation-translations).
Following rules only apply to documentations of APIs.
## Reading Electron Documentation
### Page title
Here are some tips for understanding Electron documentation syntax.
Each page must use the actual object name returned by `require('electron')`
as name, like `BrowserWindow`, `autoUpdater`, `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
`## Methods` and `## Events` chapters.
Using `autoUpdater` as example:
```markdown
# autoUpdater
## Events
### Event: 'error'
## Methods
### `autoUpdater.setFeedURL(url[, requestHeaders])`
```
### Classes
For APIs that exists as classes, or for classes that are parts of modules, they
must listed under `## Class: TheClassName` chapter. One page can have multiple
classes.
If the class has constructors, they must be listed with `###`-level titles.
The methods, events and properties of a class must be listed under
`### Instance Methods`, `### Instance Events` and `Instance Properties`
chapters.
Using `Session`, `Cookies` classes as 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
An example of [method](https://developer.mozilla.org/en-US/docs/Glossary/Method)
documentation:
The chapter of method must be in the following form:
```markdown
### `objectName.methodName(required[, optional]))`
* `required` String
* `optional` Integer (optional)
...
```
`methodName(required[, optional]))`
* `required` String (**required**)
* `optional` Integer
```
The title can be `###` or `####`-levels depending on whether it is a method of
module or class.
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.
For modules, the `objectName` is the module's name, for classes, it must be the
name of instance of the class, and must not be same with the module's name.
For example, the methods of `Session` class under `session` module must use
`ses` as `objectName`.
The 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:
@ -68,35 +171,69 @@ of argument is notated by either the common types:
[`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).
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`.
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_
```
For argument with `Array` type, it must be classified what elements the array
may include in the description below.
For argument with `Function` type, the description should make it clear how it
may be called and list the types of the arguments that passed to it.
### Events
An example of [event](https://developer.mozilla.org/en-US/docs/Web/API/Event)
documentation:
The chapter of event must be in following form:
```
Event: 'wake-up'
```markdown
### 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:
The title can be `###` or `####`-levels depending on whether it is an event of
module or class.
The arguments of an event have the same rules with methods.
### Properties
The chapter of property must be in following form:
```markdown
### session.defaultSession
...
```javascript
Alarm.on('wake-up', (time) => {
console.log(time)
})
```
The title can be `###` or `####`-levels depending on whether it is a property of
module or 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.
* 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.