Electron ドキュメントスタイルガイド
Electron ドキュメント作成のためのガイドラインです。
見出し
- 各ページは、最上位に1つの
#レベルの見出しを持つ必要があります。 - 同じページ内の章は、
##レベルの見出しを持つ必要があります。 - 副章は、ネストの深さに応じて見出しの
#の数を増やす必要があります。 - ページのタイトルは、APA タイトルケースに従う必要があります。
- すべての章は、APA センテンスケースに従う必要があります。
「クイックスタート」を例として使用
# 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でチェックされます。 - 順序なしリストには、ダッシュではなくアスタリスクを使用してください。
単語の選択
- 結果を説明する場合は、「would」よりも「will」を使用してください。
- 「on」よりも「in the ___ process」を優先してください。
API リファレンス
以下のルールは、API のドキュメントにのみ適用されます。
タイトルと説明
各モジュールのAPIドキュメントは、`require('electron')`によって返される実際のオブジェクト名（`BrowserWindow`、`autoUpdater`、`session`など）をタイトルとして使用する必要があります。
ページタイトルの直下に、モジュールの1行の説明をMarkdownの引用符（`>`で始まる）で追加します。
`session`モジュールを例として使用
# session
> Manage browser sessions, cookies, cache, proxy settings, etc.
モジュールメソッドとイベント
クラスではないモジュールでは、そのメソッドとイベントは`## メソッド`と`## イベント`の章の下に一覧表示する必要があります。
`autoUpdater`を例として使用
# autoUpdater
## Events
### Event: 'error'
## Methods
### `autoUpdater.setFeedURL(url[, requestHeaders])`
クラス
- APIクラスまたはモジュールの一部であるクラスは、`## クラス: クラス名`の章の下に一覧表示する必要があります。
- 1つのページに複数のクラスを含めることができます。
- コンストラクタは`###`レベルの見出しで一覧表示する必要があります。
- 静的メソッドは、`### 静的メソッド`の章の下に一覧表示する必要があります。
- インスタンスメソッドは、`### インスタンスメソッド`の章の下に一覧表示する必要があります。
- 戻り値を持つすべてのメソッドは、説明の先頭に「Returns `[TYPE]` - [戻り値の説明]」を付ける必要があります。
- メソッドが`Object`を返す場合、その構造はコロンと改行の後に、関数パラメータと同じスタイルで順序なしリストのプロパティを使用して指定できます。
- インスタンスイベントは、`### インスタンスイベント`の章の下に一覧表示する必要があります。
- インスタンスプロパティは、`### インスタンスプロパティ`の章の下に一覧表示する必要があります。
- インスタンスプロパティは「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) - Another parameter description.
...
見出しレベル
メソッドがモジュールに属するのかクラスに属するのかに応じて、見出しは`###`または`####`レベルにすることができます。
関数シグネチャ
モジュールの場合、`objectName`はモジュールの名前です。クラスの場合、クラスのインスタンスの名前でなければならず、モジュールの名前と同じであってはなりません。
たとえば、`session`モジュールの下の`Session`クラスのメソッドは、`ses`を`objectName`として使用する必要があります。
オプションの引数は、角括弧`[]`で囲まれたオプションの引数と、このオプションの引数の後に別の引数が続く場合に必要なコンマで表記します。
required[, optional]
引数の説明
各引数の詳細情報は、メソッドの下の順序なしリストに記載されています。引数の型は、JavaScript プリミティブ（例：`string`、`Promise`、`Object`）、Electron の CookieのようなカスタムAPI構造、またはワイルドカード`any`で表記されます。
引数の型が`Array`の場合、配列内の値の型を含む`[]`の省略記法を使用します（例：`any[]`または`string[]`）。
引数の型が`Promise`の場合、Promiseが解決する型で型をパラメーター化します（例：`Promise
引数が複数の型になる可能性がある場合は、型を`|`で区切ります。
`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](latest/api/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へのリンクと、変更の簡単な説明（オプション）を含める必要があります。該当する場合は、破壊的な変更ドキュメントからのその変更の見出しIDを含めます。
API履歴リンティングスクリプト（`lint:api-history`）は、ElectronドキュメントのAPI履歴ブロックをスキーマに対して検証し、他のチェックも実行します。詳細については、そのテストを参照してください。
リンティングスクリプトでは網羅されていないスタイルガイドラインがいくつかあります。
形式
常にこの形式に従ってください。
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
- インデントにはスペースを2つ使用してください。
- コメントを使用しないでください。
説明
- 説明は常に二重引用符で囲んでください（例：「example」）。
- アプリ開発者に関連する形で変更を説明し、大文字、句読点、過去形を使用してください。
- 例については、Clerkを参照してください。
- 説明を簡潔に保ってください。
- 理想的には、説明は破壊的な変更ドキュメントの対応するヘッダーと一致する必要があります。
- 可能な限り、関連するPRのリリースノートを使用してください。
- 開発者は、詳細については、常に破壊的変更ドキュメントまたはリンクされたプルリクエストを参照できます。
配置場所
一般的に、API履歴ブロックは、変更されたクラスまたはメソッドのMarkdownヘッダーの直後に配置する必要があります。ただし、曖昧になる場合もあります。
Chromium バージョンアップ
破壊的変更が既存のAPIのいずれにも関連しない場合があります。この場合、API履歴をどこにも追加しなくても問題ありません。
複数のAPIに影響する変更
破壊的変更が複数のAPIに関連する場合があります。この場合、API履歴ブロックを、関連する各APIの最上位のMarkdownヘッダーの下に配置します。
# 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](latest/glossary.md#renderer-process)
API履歴ブロックが以下の箇所に追加されていないことに注意してください。
contextBridge.exposeInMainWorld(apiKey, api)
この関数は変更されておらず、使用方法のみが変更されたためです。
contextBridge.exposeInMainWorld('app', {
- ipcRenderer,
+ onEvent: (cb) => ipcRenderer.on('foo', (e, ...args) => cb(args))
})
ドキュメント翻訳
electron/i18nを参照してください。