97 lines
3.7 KiB
Markdown
97 lines
3.7 KiB
Markdown
# Electron Documentation Styleguide
|
||
|
||
Find the appropriate section for your task: [reading Electron documentation](#reading-electron-documentation)
|
||
or [writing Electron documentation](#writing-electron-documentation).
|
||
|
||
## Написання документації для Electron
|
||
|
||
Існує кілька способів за допомогою яких ми ствоюємо документацію для Electron.
|
||
|
||
- 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)` _OS X_```
|
||
- Prefer 'in the ___ process' over 'on'
|
||
|
||
### Переклад документації
|
||
|
||
Переклади документації знаходяться в дерикторії `docs-translations`.
|
||
|
||
Щоб додати переклад (або частковий переклад) документації:
|
||
|
||
- 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/atom/electron#documentation-translations).
|
||
|
||
## Читання документації Electron
|
||
|
||
Кілька порад для того щоб легше зрозуміти синтаксис документації Electron.
|
||
|
||
### Методи
|
||
|
||
Приклад [методу](https://developer.mozilla.org/en-US/docs/Glossary/Method)
|
||
в документації:
|
||
|
||
---
|
||
|
||
`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).
|
||
|
||
### Події
|
||
|
||
Приклад [події](https://developer.mozilla.org/en-US/docs/Web/API/Event)
|
||
в документації:
|
||
|
||
---
|
||
|
||
Подія: 'wake-up'
|
||
|
||
Повердає:
|
||
|
||
* `time` Текст
|
||
|
||
---
|
||
|
||
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)
|
||
})
|
||
```
|