Electron ドキュメントスタイルガイド
Electronのドキュメント（英語）を書くためのガイドラインです。
ヘッディング
- Each page must have a single
#-level title at the top. - Chapters in the same page must have
##-level headings. - Sub-chapters need to increase the number of
#in the heading according to their nesting depth. - The page's title must follow APA title case.
- All chapters must follow APA sentence case.
Using Quick Start as example:
# Quick Start
...
## Main process
...
## Renderer process
...
## Run your app
...
### Run as a distribution
...
### Manually downloaded Electron binary
...
ただし、 API リファレンスに関してはこのルールの例外があります。
Markdown のルール
This repository uses the markdownlint package to enforce consistent
Markdown styling. For the exact rules, see the .markdownlint.json file in the root
folder.
リンターのルールではカバーしきれないような、いくつかのスタイルガイドラインを以下に示します。
- Use
shinstead ofcmdin code blocks (due to the syntax highlighter). - Keep line lengths between 80 and 100 characters if possible for readability purposes.
- 2 階層以上にネストしたリストは使用できません (Markdown レンダラーのため)。
- All
jsandjavascriptcode blocks are linted with 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 >).
Using the session module as an example:
# session
> Manage browser sessions, cookies, cache, proxy settings, etc.
モジュールメソッドとイベント
For modules that are not classes, their methods and events must be listed under
the ## Methods and ## Events chapters.
Using autoUpdater as an example:
# autoUpdater
## Events
### Event: 'error'
## Methods
### `autoUpdater.setFeedURL(url[, requestHeaders])`
クラス
- API classes or classes that are part of modules must be listed under a
## Class: TheClassNamechapter. - 1 ページに複数のクラスがあってもかまいません。
- Constructors must be listed with
###-level headings. - Static Methods
must be listed under a
### Static Methodschapter. - Instance Methods
must be listed under an
### Instance Methodschapter. - 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 Events must be listed under an
### Instance Eventschapter. - Instance Properties must be listed under an
### Instance Propertieschapter.- インスタンスプロパティは "A [プロパティの型] ..." で始まる必要があります。
Using the Session and Cookies classes as an example:
# session
## Methods
### session.fromPartition(partition)
## Static Properties
### session.defaultSession
## Class: Session
### Instance Events
#### Event: 'will-download'
### Instance Methods
#### `ses.getCacheSize()`
### Instance Properties
#### `ses.cookies`
## Class: Cookies
### Instance Methods
#### `cookies.get(filter, callback)`
メソッドとその引数
メソッドの章はつぎの形式でなければなません。
### `objectName.methodName(required[, optional]))`
* `required` string - A parameter description.
* `optional` Integer (optional) - Another parameter description.
...
見出しレベル
The heading can be ### or ####-levels depending on whether the method
belongs to a module or a class.
関数シグネチャ
For modules, the objectName is the module's name. クラスでは、クラスのインスタンスの名前にするべきで、モジュールの名前と同じではいけません。
For example, the methods of the Session class under the session module must
use ses as the 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:
必須[, 任意]
引数の説明
各引数の詳細は、そのメソッドの下に順序なしリストで記載します。 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 |.
The description for Function type arguments should make it clear how it may be
called and list the types of the parameters that will be passed to it.
プラットフォーム固有の引数
引数またはメソッドが特定のプラットフォーム固有のものである場合、そのプラットフォームはデータ型に続くスペース区切りのイタリック体リストを用いて示されます。 Values
can be macOS, Windows or 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 履歴
「API 履歴」ブロックは、HTML コメントでカプセル化された YAML コードブロックであり、以下のようにクラスやメソッドの Markdown 見出しの直後に配置する必要があります。
#### `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: "`trafficLightPosition` オプションが `customButtonOnHover` のウインドウで機能するようにしました。"
deprecated:
- pr-url: https://github.com/electron/electron/pull/37094
breaking-changes-header: deprecated-browserwindowsettrafficlightpositionposition
```
-->
* `position` [Point](structures/point.md)
信号機ボタンのカスタム位置を設定します。`titleBarStyle` が `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.
API 履歴ブロックの目的は、API の以下のようなことについて、いつ/どこで/どのように/なぜを説明することです。
- 追加
- 変更 (大抵は破壊的変更)
- 非推奨
ブロックにリストする各 API 変更には、その変更が行われた PR へのリンクと、任意で変更の短い説明を含める必要があります。 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.
lint スクリプトではカバーしきれないような、いくつかのスタイルガイドラインを以下に示します。
フォーマット
常にこのフォーマットに準拠してください。
API HEADER | #### win.flashFrame(flag)
BLANK LINE |
HTML COMMENT OPENING TAG |
BLANK LINE |
YAML
- インデントにはスペース 2 つを使用します。
- コメントは使用しないでください。
説明
- 説明は常に二重引用符で囲みます (例: "example")。
- Describe the change in a way relevant to app developers and make it
capitalized, punctuated, and past tense.
- Refer to Clerk for examples.
- 説明は簡潔にしてください。
- Ideally, a description will match its corresponding header in the breaking changes document.
- できる限り関連 PR のリリースノートを引用してください。
- Developers can always view the breaking changes document or linked pull request for more details.
配置
一般的に、API 履歴ブロックは変更が入ったクラスｙｓメソッドの Markdown 見出しの直後に配置する必要があります。 ただし、以下のようにこれが曖昧な例がいくつかあります。
Chromium の更新
場合によっては、重大な変更が既存 API のいずれにも関係しないことがあります。 この場合、API 履歴をどこにも追加しなくても構いません。
複数の API へ影響する変更
場合によっては、重大な変更に複数の API が関係することがあります。 この場合、関係する各 API の最上位の Markdown 見出しの下に API 履歴ブロックを配置します。
# 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)
注意として、次の場所には API 履歴ブロックは追加されていません。
contextBridge.exposeInMainWorld(apiKey, api)
なぜならその関数は変更されておらず、その使用方法が変化しただけだからです。
contextBridge.exposeInMainWorld('app', {
- ipcRenderer,
+ onEvent: (cb) => ipcRenderer.on('foo', (e, ...args) => cb(args))
})
ドキュメントの翻訳
See electron/i18n