Electron 文檔風格指南

標題

• 每個頁面頂部必須有一個單獨的 ＃ 級標題。
• 同一頁面中的章節(jié)必須有 ## 級標題。
• 子章節(jié)需要根據(jù)它們的嵌套深度增加標題中的 ＃ 數(shù)量。
• 頁面標題中的所有單詞首字母都必須大寫，除了 “of” 和 “and” 之類的連接詞。
• 只有章節(jié)標題的第一個單詞首字母必須大寫.

舉一個 Quick Start 的例子:

# Quick Start

...

## Main process

...

## Renderer process

...

## Run your app

...

### Run as a distribution

...

### Manually downloaded Electron binary

...

對于 API 參考, 可以例外于這些規(guī)則.

Markdown 規(guī)則

• 在代碼塊中使用 bash 而不是 cmd（由于語法高亮問題）.
• 行長度應該控制在80列內(nèi).
• 列表嵌套不超出2級 (由于 Markdown 渲染問題).
• 所有的 js 和 javascript 代碼塊均被標記為 standard-markdown.

用詞選擇

• 在描述結(jié)果時，使用 “will” 而不是 “would”。
• 首選 "in the ___ process" 而不是 "on".

API 參考

以下規(guī)則僅適用于 API 的文檔。

頁面標題

每個頁面必須使用由 require（'electron'） 返回的實際對象名稱作為標題，例如 BrowserWindow，autoUpdater 和 session。

在頁面標題下必須是以 > 開頭的單行描述。

舉一個 session 的例子:

# session

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

模塊方法和事件

對于非類的模塊，它們的方法和事件必須在 ## Methods 和 ## Events 章節(jié)中列出。

舉一個 autoUpdater 的例子:

# autoUpdater

## Events

### Event: 'error'

## Methods

### `autoUpdater.setFeedURL(url[, requestHeaders])`

類

• API 類或作為模塊一部分的類必須在 ## Class: TheClassName 章節(jié)中列出.
• 一個頁面可以有多個類.
• 構(gòu)造函數(shù)必須用 ### 級標題列出.
• 靜態(tài)方法 必須在 ### Static Methods 章節(jié)中列出.
• 實例方法 必須在 ### Instance Methods 章節(jié)中列出.
• 所有具有返回值的方法必須用 "Returns [TYPE] - Return description" 的形式描述.
  • 如果該方法返回一個 Object，則可以使用冒號后跟換行符，然后使用與函數(shù)參數(shù)相同樣式的屬性的無序列表來指定其結(jié)構(gòu).
• 實例事件必須在 ### Instance Events 章節(jié)中列出.
• 實例屬性必須在 ### Instance Properties 章節(jié)中列出.
  • 實例屬性必須以 "A [Property Type] ..." 開始描述.

這里用 Session 和 Cookies 類作為例子:

# session

## Methods

### session.fromPartition(partition)

## Properties

### session.defaultSession

## Class: Session

### Instance Events

#### Event: 'will-download'

### Instance Methods

#### `ses.getCacheSize(callback)`

### Instance Properties

#### `ses.cookies`

## Class: Cookies

### Instance Methods

#### `cookies.get(filter, callback)`

方法

方法章節(jié)必須采用以下形式：

### `objectName.methodName(required[, optional]))`

* `required` String - A parameter description.
* `optional` Integer (optional) - Another parameter description.

...

標題可以是 ### 級別或 #### 級別，具體取決于它是模塊還是類的方法。

對于模塊，objectName 是模塊的名稱。 對于類，它必須是類的實例的名稱，并且不能與模塊的名稱相同。

例如，session 模塊下的 Session 類的方法必須使用 ses 作為 objectName 。

可選參數(shù)由圍繞可選參數(shù)的方括號 [] 表示，并且如果此可選參數(shù)跟隨另一個參數(shù)，則需要逗號：

required[, optional]

下面的方法是每個參數(shù)更加詳細的信息。 參數(shù)的類型由常見類型表示:

• String
• Number
• Object
• Array
• Boolean
• 或自定義類型,就像 Electron 的 WebContent

如果參數(shù)或方法對某些平臺是唯一的，那么這些平臺將使用數(shù)據(jù)類型后面的空格分隔的斜體列表來表示。 值可以是 macOS，Windows 或 Linux

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

Array 類型的參數(shù), 必須在指定數(shù)組下面的描述中描述可能包含的元素.

Function 類型參數(shù)的描述應該清楚描述它是如何被調(diào)用的，并列出將被傳遞給它的參數(shù)的類型.

事件

事件章節(jié)必須采用以下形式:

### Event: 'wake-up'

Returns:

* `time` String

...

標題可以是 ### 級別或 #### 級別，具體取決于它是模塊還是類的事件。

事件的參數(shù)遵循與方法相同的規(guī)則.

屬性

屬性章節(jié)必須采用以下形式:

### session.defaultSession

...

標題可以是 ### 級別或 #### 級別，具體取決于它是模塊還是類的屬性。

文檔翻譯

Electron 文檔的翻譯文件位于 docs-translations 目錄中.

如要添加另一個設定集（或部分設定集）:

• 創(chuàng)建以語言縮寫命名的子目錄。
• 翻譯文件。
• 更新您的語言目錄中的 README.md 文件以鏈接到已翻譯的文件。
• 在 Electron 的主 README 上添加到翻譯目錄的鏈接。

請注意，docs-translations 下的文件只能包含已被翻譯的文件，不應將原始英語文件復制到那里。