Electron ドキュメントスタイルガイド
Electronのドキュメント（英語）を書くためのガイドラインです。
ヘッディング
- 各ページは最上部に1つの
#レベルのタイトルが必要です。 - 同じページの章には、
##レベルの見出しが必要です。 - 節の見出しは、ネストする深さに応じて増やした
#が必要です。 - ページのタイトルは APA タイトルケース に従う必要があります。
- すべての章のタイトルは APA タイトルケース に従う必要があります。
Quick Start（クイックスタート） を例にすると、以下のようになります。
# Quick Start
...
## Main process
...
## Renderer process
...
## Run your app
...
### Run as a distribution
...
### Manually downloaded Electron binary
...
ただし、 API リファレンスに関してはこのルールの例外があります。
Markdown のルール
このリポジトリでは、一貫した Markdown スタイルにするために markdownlint パッケージを使用しています。 正確なルールについては、ルートフォルダ内の .markdownlint.json ファイルをご参照ください。
リンターのルールではカバーしきれないような、いくつかのスタイルガイドラインを以下に示します。
- コードブロックでは
cmdの代わりにshを使用します (構文ハイライトのため)。 - 可読性を考慮し、行の長さはできるだけ 80 から 100 文字にしてください。
- 2 階層以上にネストしたリストは使用できません (Markdown レンダラーのため)。
- すべての
jsとjavascriptコードブロックは、standard-markdown によって整形されます。 - 順序無しリストには、ダッシュではなくアスタリスクを使用してください。
使用する言葉
- 結果を説明するときは、「なるでしょう」より「なります」を使用します。
- 「プロセス上」より「プロセス内」が望ましいです。
API リファレンス
以下のルールは、API のドキュメントにのみ適用されます。
タイトルと説明
各モジュールの API ドキュメントでは、require('electron') が返す実際のオブジェクト名をタイトルとして使用しなければなりません (BrowserWindow、autoUpdater、session など)。
ページタイトル直下に、モジュールの説明を 1 行で Markdown の引用文として (> 始まりで) 追加します。
session モジュールを例にすると、以下のようにします。
# session
> ブラウザーセッション、Cookie、キャッシュ、プロキシ設定などを管理します。
モジュールメソッドとイベント
モジュールはクラスではありません。そのメソッドとイベントは ## Methods と ## Events の章の下に列挙しなければなりません。
autoUpdater を例にすると、以下のようになります。
# autoUpdater
## Events
### Event: 'error'
## Methods
### `autoUpdater.setFeedURL(url[, requestHeaders])`
クラス
- API のクラスやモジュールの一部の API クラスは
## Class: クラス名の章の下に列挙しなければなりません。 - 1 ページに複数のクラスがあってもかまいません。
- コンストラクタは
###階層のタイトルで列挙する必要があります。 - 静的メソッド は
### Static Methodsの章の配下に列挙しなければなりません。 - インスタンスメソッド は
### Instance Methodsの章の配下に列挙しなければなりません。 - すべての戻り値があるメソッドの説明は、"Returns
[TYPE][戻り値の説明]" というように書き始めてください。- メソッドが
Objectを返す場合、その構造を記述します。コロンとそれに続く改行、そして関数の引数と同じスタイルでプロパティの順序なしリストにします。
- メソッドが
- Instance Events は
### Instance Eventsの章の下に列挙しなければなりません。 - Instance Properties は
### Instance Propertiesの章の下に列挙しなければなりません。- インスタンスプロパティは "A [プロパティの型] ..." で始まる必要があります。
Session と Cookies クラスを例にすると、以下のようにします。
# 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) - 他の引数の説明。
...
見出しレベル
見出しは、メソッドがモジュールに属するかクラスに属するかに応じて、### か #### レベルになります。
関数シグネチャ
モジュールでは、objectName がモジュールの名前です。 クラスでは、クラスのインスタンスの名前にするべきで、モジュールの名前と同じではいけません。
例として、session モジュール下の Session クラスのメソッドは ses を objectName として使用しなければなりません。
任意の引数は、角括弧 [] で囲んで表記し、この任意の引数が他の引数に続く場合はカンマが必要です。
必須[, 任意]
引数の説明
各引数の詳細は、そのメソッドの下に順序なしリストで記載します。 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.
引数の型が Array の場合は、配列内の値の型に [] の省略形を使用してください (例えば、any[] や string[])。
引数が Promise 型の場合、Promise が何に解決するかを型引数にします (例えば、Promise<void> や Promise<string>)。
引数が複数の型を取りうる場合は、| で型を区切ります。
Function 型引数の説明は、それがどのように呼ばれるのかを明確にし、それに渡される引数の型を列挙しなければなりません。
プラットフォーム固有の引数
引数またはメソッドが特定のプラットフォーム固有のものである場合、そのプラットフォームはデータ型に続くスペース区切りのイタリック体リストを用いて示されます。 値は macOS、Windows、Linux にできます。
* `animate` boolean (optional) _macOS_ _Windows_ - Animate the thing.
イベント
イベントの章はつぎの形式でなければなません。
### Event: 'wake-up'
Returns:
* `time` string
...
見出しは、イベントがモジュールに属するかクラスに属するかに応じて、### か #### レベルになります。
イベントの引数についてはメソッドと同じルールに従います。
プロパティ
プロパティの章はつぎの形式でなければなません。
### session.defaultSession
...
見出しは、プロパティがモジュールに属するかクラスに属するかに応じて、### か #### レベルになります。
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: "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`.
これは、docs フォルダにある API 履歴の JSON スキーマ (api-history.schema.json) に準拠しなければなりません。 API 履歴スキーマ RFC には、使用例とスキーマの各部分の詳細な説明が含まれています。
API 履歴ブロックの目的は、API の以下のようなことについて、いつ/どこで/どのように/なぜを説明することです。
- 追加
- 変更 (大抵は破壊的変更)
- 非推奨
ブロックにリストする各 API 変更には、その変更が行われた PR へのリンクと、任意で変更の短い説明を含める必要があります。 If applicable, include the heading id for that change from the breaking changes documentation.
API 履歴の lint スクリプト (
lint:api-history) は、Electron ドキュメント内の API 履歴ブロックをスキーマに対して検証し、その他のチェックを実行します。 詳細については テスト をご確認ください。 lint スクリプトではカバーしきれないような、いくつかのスタイルガイドラインを以下に示します。
フォーマット
常にこのフォーマットに準拠してください。
API 見出し | #### `win.flashFrame(flag)`
空行 |
HTML コメント開始タグ | <!--
API 履歴開始タグ | ```YAML history
API 履歴 | added:
| - pr-url: https://github.com/electron/electron/pull/22533
API 履歴終了タグ | ```
HTML コメント終了タグ | -->
空行 |
YAML
- インデントにはスペース 2 つを使用します。
- コメントは使用しないでください。
説明
- 説明は常に二重引用符で囲みます (例: "example")。
- アプリ開発者にとって関連性のある方法で、変更を説明し、文は大文字で始めて、句読点を使い、過去形を使用します。
- 例については、Clerk を参照してください。
- 説明は簡潔にしてください。
- 理想的には、説明は重大な変更のドキュメント内の対応する見出しと一致します。
- できる限り関連 PR のリリースノートを引用してください。
- 開発者が詳細を確認するために、重大な変更に関するドキュメントまたはリンクされたプルリクエストをいつでも確認できるようにしてください。
配置
一般的に、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))
})
ドキュメントの翻訳
electron/i18n を参照してください