メインコンテンツへ飛ぶ

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 で lint されます。
  • 順序無しリストには、ダッシュではなくアスタリスクを使用してください。

使用する言葉​

  • 結果を説明するときは、「なるでしょう」より「なります」を使用します。
  • 「プロセス上」より「プロセス内」が望ましいです。

API リファレンス​

以下のルールは、API のドキュメントにのみ適用されます。

タイトルと説明​

各モジュールの API ドキュメントでは、require('electron') が返す実際のオブジェクト名をタイトルとして使用しなければなりません (BrowserWindow、autoUpdater、session など)。

ページタイトル直下に、モジュールの説明を 1 行で Markdown の引用文として (> 始まりで) 追加します。

session モジュールを例にすると、以下のようにします。

# session

> Manage browser sessions, cookies, cache, proxy settings, etc.

モジュールメソッドとイベント​

クラスではないモジュールの場合、そのメソッドとイベントは ## 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 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) - Another parameter description.

...

見出しレベル​

見出しは、メソッドがモジュールに属するかクラスに属するかに応じて、### か #### レベルになります。

関数シグネチャ​

モジュールでは、objectName がモジュールの名前です。 クラスでは、クラスのインスタンスの名前にするべきで、モジュールの名前と同じではいけません。

たとえば、session モジュールの Session クラスのメソッドでは、objectName として ses を使用する必要があります。

任意の引数は、角括弧 [] で囲んで表記し、この任意の引数が他の引数に続く場合はカンマが必要です。

必須[, 任意]

引数の説明​

各引数の詳細は、そのメソッドの下に順序なしリストで記載します。 引数の種類は、JavaScript のプリミティブ (例: string、Promise、Object)、Electron の Cookie のようなカスタム API の構造体、またはワイルドカードである 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: "`trafficLightPosition` オプションが `customButtonOnHover` のウインドウで機能するようにしました。"
deprecated:
  - pr-url: https://github.com/electron/electron/pull/37094
    breaking-changes-header: deprecated-browserwindowsettrafficlightpositionposition
```
-->

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

信号機ボタンのカスタム位置を設定します。`titleBarStyle` が `hidden` に設定されている場合にのみ使用できます。

これは、 フォルダにある API 履歴の JSON スキーマ (api-history.schema.json) に準拠しなければなりません。 API 更新履歴のスキーマの RFC には、使用例とスキーマの各部分の詳細な説明が含まれています。

API 履歴ブロックの目的は、API の以下のようなことについて、いつ/どこで/どのように/なぜを説明することです。

  • 追加
  • 変更 (大抵は破壊的変更)
  • 非推奨

ブロックにリストする各 API 変更には、その変更が行われた PR へのリンクと、任意で変更の短い説明を含める必要があります。 該当する場合は、破壊的変更に関するドキュメント からその変更の 見出し ID を含めてください。

API 変更履歴の lint スクリプト (lint:api-history) は、Electron ドキュメント内の API 更新履歴ブロックをスキーマに対して検証し、その他のチェックを実行します。 詳細については テスト をご確認ください。

lint スクリプトではカバーしきれないような、いくつかのスタイルガイドラインを以下に示します。

フォーマット​

常にこのフォーマットに準拠してください。

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 の最上位の 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 をご参照ください