78 lines
2.7 KiB
Markdown
78 lines
2.7 KiB
Markdown
# Electron Documentation Styleguide
|
|
|
|
Find the appropriate section for your task: [reading Electron documentation](#)
|
|
or [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
|
|
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)` _Mac_```
|
|
|
|
## 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]))`
|
|
|
|
* `require` 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).
|
|
|
|
### 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', function(time) {
|
|
console.log(time)
|
|
})
|
|
```
|