Руководство по стилю доку ментации Electron
Это руководство для написания Electron документации.
Заголовки
- Каждая страница должна иметь один заголовок
#
в верхней части. - Главы на одной странице должны иметь
##
-уровневые заголовки. - Подглавы должны увеличивать количество
#
в заголовке в соответствии с глубиной их вложенности. - Название страницы должно соответствовать титульному листу APA.
- Все главы должны соответствовать правилам регистра предложений APA.
Используйте Быстрый старт
как пример:
# Быстрый старт
...
## Основной процесс
...
## Процесс визуализации
...
## Запустите приложение
...
### Запустите как дистрибутив
...
### Ручная загрузка файла Electron
...
Для ссылок на API есть исключения из эт ого правила.
Markdown правила
Этот репозиторий использует пакет markdownlint
для обеспечения согласованности стиля Markdown. Для уточнения правил обратитесь к файлу .markdownlint.json
в корневой папке.
Есть несколько руководств по стилю, которые не охватываются правилами линтера:
- Используйте
sh
вместоcmd
в блоках кода (из-за синтаксической подсветки). - Если возможно, длина строки должна быть 80-100 символов для читабельности.
- Не делать вложенные списки более чем 2 уровня (из-за markdown отображения).
- Все блоки кода
js
иjavascript
проверяются линтером по standard-markdown. - Для неупорядоченных списков используйте звёздочки вместо тире.
Выбор слов
- Используйте "будет" вместо "был бы" при описании результатов.
- Предпочитайте "в ___ процессе" чем "в".
Справочник по API
Следующие правила применяются только к документации по API.
Заголовок и описание
Each module's API doc must use the actual object name returned by require('electron')
as its title (such as BrowserWindow
, autoUpdater
, and session
).
Directly under the page title, add a one-line description of the module as a markdown quote (beginning with >
).
Используйте модуль session
, как это описано ниже:
# session
> Управление сеансами браузера, куками, кешем, настройками прокси и т.д.
Методы и события модуля
Для модулей, которые не являются классами, методы и события должны быть перечислены под главами ## Методы
и ## События
.
Используйте autoUpdater
как пример:
# autoUpdater
## События
### Событие: 'error'
## Методы
### `autoUpdater.setFeedURL(url[, requestHeaders])`
Классы
- Классы API или классы, которые являются частью модулей должны быть перечислены под главой
## Класс: НазваниеКласса
. - Одна страница может иметь несколько классов.
- Constructors must be listed with
###
-level headings. - Static Methods must be listed under a
### Static Methods
chapter. - Instance Methods must be listed under an
### Instance Methods
chapter. - All methods that have a return value must start their description with "Returns
[TYPE]
- [Return description]"- If the method returns an
Object
, its structure can be specified using a colon followed by a newline then an unordered list of properties in the same style as function parameters.
- If the method returns an
- События экземпляров, должны быть перечислены под главой
### События экземпляра
. - Instance Properties must be listed under an
### Instance Properties
chapter.- Instance Properties must start with "A [Property Type] ..."
Используйте классы Session
и Cookies
в качестве примера:
# session
## Методы
### session.fromPartition(partition)
## Ста тические свойства
### session.defaultSession
## Class: Session
### События экземпляра
#### Event: 'will-download'
### Методы экземпляра
#### `ses.getCacheSize()`
### Свойства экземпляра
#### `ses.cookies`
## Class: Cookies
### Методы экземпляра
#### `cookies.get(filter, callback)`
Методы и их аргументы
Методы главы должны быть в следующем виде:
### `objectName.methodName(required[, optional]))`
* `required` string - A parameter description.
* `optional` Integer (optional) - Another parameter description.
...
Уровень заголовка
Заголовок может б ыть уровня ###
или####
, в зависимости от того, относится ли этот метод к модулю или к классу.
Подпись функции
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.
Например, методы класса Session
под модулем session
должны использовать ses
как objectName
.
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]
Описания аргументов
More detailed information on each of the arguments is noted in an unordered list below the method. The type of argument is notated by either JavaScript primitives (e.g. string
, Promise
, or Object
), a custom API structure like Electron's Cookie, or the wildcard any
.
If the argument is of type Array
, use []
shorthand with the type of value inside the array (for example,any[]
or string[]
).
If the argument is of type Promise
, parametrize the type with what the promise resolves to (for example, Promise<void>
or Promise<string>
).
If an argument can be of multiple types, separate the types with |
.
Описание аргументов типа Function
должно дать понять, как это может быть вызвано и перечислить типы параметров, которые будут переданы ему.