Перейти к основному содержанию

Руководство по стилю документации Electron

Это руководство для написания Electron документации.

Заголовки​

  • Каждая страница должна иметь один заголовок # в верхней части.
  • Главы на одной странице должны иметь ##-уровневые заголовки.
  • Подглавы должны увеличивать количество # в заголовке в соответствии с глубиной их вложенности.
  • Название страницы должно соответствовать титульному листу APA.
  • Все главы должны соответствовать правилам регистра предложений APA.

Используйте Быстрый старт как пример:

# Быстрый старт

...

## Основной процесс

...

## Процесс визуализации

...

## Запустите приложение

...

### Запустите как дистрибутив

...

### Ручная загрузка файла Electron

...

Для ссылок на API есть исключения из этого правила.

Markdown правила​

Этот репозиторий использует пакет markdownlint для обеспечения согласованности стиля Markdown. Для уточнения правил обратитесь к файлу .markdownlint.json в корневой папке.

Есть несколько руководств по стилю, которые не охватываются правилами линтера:

  • Используйте sh вместо cmd в блоках кода (из-за синтаксической подсветки).
  • Если возможно, длина строки должна быть 80-100 символов для читабельности.
  • Не делать вложенные списки более чем 2 уровня (из-за markdown отображения).
  • Все блоки кода js и javascript проверяются линтером по standard-markdown.
  • Для неупорядоченных списков используйте звёздочки вместо тире.

Выбор слов​

  • Используйте "будет" вместо "был бы" при описании результатов.
  • Предпочитайте "в ___ процессе" чем "в".

Справочник по API​

Следующие правила применяются только к документации по API.

Заголовок и описание​

Каждая страница должна использовать имя фактического объекта, возвращенное require('electron') (как название, такие как BrowserWindow, autoUpdater и session).

Под заголовком страницы добавьте однострочное описание модуля в виде цитаты markdown (начиная с >).

Используйте модуль 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.
  • События экземпляров, должны быть перечислены под главой ### События экземпляра.
  • 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 должно дать понять, как это может быть вызвано и перечислить типы параметров, которые будут переданы ему.

Функциональность, зависящая от платформы​

Если аргумент или метод является уникальным для определенных платформ, эти платформы обозначаются списком, разделенных пробелами, после типа данных. Значения могут быть macOS, Windows или Linux.

* `animate` boolean (optional) _macOS_ _Windows_ - Animate the thing.

События​

Глава события должна быть в следующем виде:

### Event: 'wake-up'

Returns:

* `time` string

...

The heading can be ### or ####-levels depending on whether the event belongs to a module or a class.

Аргументы события следуют тем же правилам методов.

Свойства​

Глава свойства должна быть в следующем виде:

### session.defaultSession

...

The heading can be ### or ####-levels depending on whether the property belongs to a module or a class.

История API​

An "API History" block is a YAML code block encapsulated by an HTML comment that should be placed directly after the Markdown header for a class or method, like so:

#### `win.setTrafficLightPosition(position)` _macOS_

<!--
```YAML history
added:
  - pr-url: https://github.com/electron/electron/pull/22533
changes:
  - pr-url: https://github.com/electron/electron/pull/26789
    description: "Made `trafficLightPosition` option work for `customButtonOnHover` window."
deprecated:
  - pr-url: https://github.com/electron/electron/pull/37094
    breaking-changes-header: deprecated-browserwindowsettrafficlightpositionposition
```
-->

* `position` [Point](structures/point.md)

Set a custom position for the traffic light buttons. Can only be used with `titleBarStyle` set to `hidden`.

It should adhere to the API History JSON Schema (api-history.schema.json) which you can find in the docs folder. The API History Schema RFC includes example usage and detailed explanations for each aspect of the schema. The purpose of the API History block is to describe when/where/how/why an API was:

  • Added
  • Changed (usually breaking changes)
  • Deprecated Each API change listed in the block should include a link to the PR where that change was made along with an optional short description of the change. If applicable, include the heading id for that change from the breaking changes documentation. The API History linting script (lint:api-history) validates API History blocks in the Electron documentation against the schema and performs some other checks. You can look at its tests for more details. There are a few style guidelines that aren't covered by the linting script:

Format​

Always adhere to this format:

API HEADER                  |  #### `win.flashFrame(flag)`
BLANK LINE                  | 
HTML COMMENT OPENING TAG    |  <!--
API HISTORY OPENING TAG     |  ```YAML history
API HISTORY                 |  added:
                            |    - pr-url: https://github.com/electron/electron/pull/22533
API HISTORY CLOSING TAG     |  ```
HTML COMMENT CLOSING TAG    |  -->
BLANK LINE                  |

YAML​

  • Use two spaces for indentation.
  • Do not use comments.

Descriptions​

  • Always wrap descriptions with double quotation marks (i.e. "example").
  • Describe the change in a way relevant to app developers and make it capitalized, punctuated, and past tense.
    • Refer to Clerk for examples.
  • Keep descriptions concise.
    • Ideally, a description will match its corresponding header in the breaking changes document.
    • Favor using the release notes from the associated PR whenever possible.
    • Developers can always view the breaking changes document or linked pull request for more details.

Placement​

Generally, you should place the API History block directly after the Markdown header for a class or method that was changed. However, there are some instances where this is ambiguous:

Chromium bump​

Sometimes a breaking change doesn't relate to any of the existing APIs. In this case, it is ok not to add API History anywhere.

Change affecting multiple APIs​

Sometimes a breaking change involves multiple APIs. In this case, place the API History block under the top-level Markdown header for each of the involved APIs.

# contextBridge

<!--
```YAML history
changes:
  - pr-url: https://github.com/electron/electron/pull/40330
    description: "`ipcRenderer` can no longer be sent over the `contextBridge`"
    breaking-changes-header: behavior-changed-ipcrenderer-can-no-longer-be-sent-over-the-contextbridge
```
-->

> Create a safe, bi-directional, synchronous bridge across isolated contexts
# ipcRenderer

<!--
```YAML history
changes:
  - pr-url: https://github.com/electron/electron/pull/40330
    description: "`ipcRenderer` can no longer be sent over the `contextBridge`"
    breaking-changes-header: behavior-changed-ipcrenderer-can-no-longer-be-sent-over-the-contextbridge
```
-->

Process: [Renderer](../glossary.md#renderer-process)

Notice how an API History block wasn't added under:

  • contextBridge.exposeInMainWorld(apiKey, api) since that function wasn't changed, only how it may be used:
  contextBridge.exposeInMainWorld('app', {
-   ipcRenderer,
+   onEvent: (cb) => ipcRenderer.on('foo', (e, ...args) => cb(args))
  })

Переводы документации​

См. electron/i18n