Electron 文档风格指南

这里是一些编写 Electron 文档的指南。

标题

  • 每个页面顶部必须有一个 # 级标题。
  • 同一页面中的各章节必须有 ## 级标题。
  • 各小节需要根据其嵌套层级增加 # 的数量。
  • 页面标题中的所有单词首字母都必须大写,除了 “of” 和 “and” 之类的连接词。
  • 章节名只有第一个单词首字母必须大写。

举一个Quick Start的例子:

  1. # Quick Start
  2. ...
  3. ## Main process
  4. ...
  5. ## Renderer process
  6. ...
  7. ## Run your app
  8. ...
  9. ### Run as a distribution
  10. ...
  11. ### Manually downloaded Electron binary
  12. ...

对于 API 参考, 可以例外于这些规则.

Markdown 规则

  • 在代码块中使用bash而不是cmd(由于语法高亮问题).
  • 行长度应该控制在80列内.
  • 列表嵌套不超出2级 (由于 Markdown 渲染问题).
  • 所有的jsjavascript代码块均被标记为 standard-markdown.

用词选择

  • 在描述结果时,使用 “will” 而不是 “would”。
  • 首选 “in the _ process” 而不是 “on”.

API 参考

以下规则仅适用于 API 的文档。

页面标题

每个页面必须使用由 require('electron') 返回的实际对象名称作为标题,例如BrowserWindowautoUpdatersession

在页面下方标题必须是以>开头的单行描述。

举一个 session 的例子:

  1. # session
  2. > Manage browser sessions, cookies, cache, proxy settings, etc.

模块方法和事件

对于非类的模块,它们的方法和事件必须在 ## Methods## Events章节中列出

举一个 autoUpdater 的例子:

  1. # autoUpdater
  2. ## Events
  3. ### Event: 'error'
  4. ## Methods
  5. ### `autoUpdater.setFeedURL(url[, requestHeaders])`

  • API 类或作为模块一部分的类必须在 ## Class: TheClassName 章节中列出.
  • 一个页面可以有多个类.
  • 构造函数必须用 ### 级标题列出.
  • 静态方法 必须在 ### Static Methods 章节中列出.
  • 实例方法 必须在 ### Instance Methods 章节中列出.
  • 所有具有返回值的方法必须用”Returns [TYPE] - Return description” 的形式描述.
    • 如果该方法返回一个 Object,则可以使用冒号后跟换行符,然后使用与函数参数相同样式的属性的无序列表来指定其结构.
  • 实例事件必须在 ### Instance Events 章节中列出.
  • 实例属性必须在 ### 实例属性 章节中列出.
    • 实例属性必须以 “A [Property Type] …” 开始描述.

这里用 SessionCookies 类作为例子:

  1. # session
  2. ## Methods
  3. ### session.fromPartition(partition)
  4. ## Static Properties
  5. ### session.defaultSession
  6. ## Class: Session
  7. ### Instance Events
  8. #### Event: 'will-download'
  9. ### Instance Methods
  10. #### `ses.getCacheSize()`
  11. ### Instance Properties
  12. #### `ses.cookies`
  13. ## Class: Cookies
  14. ### Instance Methods
  15. #### `cookies.get(filter, callback)`

方法

方法章节必须采用以下形式:

  1. ### `objectName.methodName(required[, optional]))`
  2. * `required` String - A parameter description.
  3. * `optional` Integer (optional) - Another parameter description.
  4. ...

标题可以是 ### 级别或 #### 级别,具体取决于它是模块还是类的方法。

对于模块,objectName 是模块的名称。 对于类,它必须是类的实例的名称,并且不能与模块的名称相同。

例如,session 模块下的 Session 类的方法必须使用 ses 作为 objectName

可选参数由围绕可选参数的方括号 [] 表示,并且如果此可选参数跟随另一个参数,则需要逗号:

  1. required[, optional]

下面的方法是每个参数更加详细的信息。 参数的类型由常见类型表示:

如果参数或方法对某些平台是唯一的,那么这些平台将使用数据类型后面的空格分隔的斜体列表来表示。 值可以是 macOSWindowsLinux.

  1. * `animate` Boolean (optional) _macOS_ _Windows_ - 进行动画处理的事情.

Array 类型的参数, 必须在指定数组下面的描述中描述可能包含的元素.

Function 类型参数的描述应该清楚描述它是如何被调用的,并列出将被传递给它的参数的类型.

事件

事件章节必须采用以下形式:

  1. ### Event: 'wake-up'
  2. Returns:
  3. * `time` String
  4. ...

标题可以是 ### 级别或 #### 级别,具体取决于它是模块还是类的事件。

事件的参数遵循与方法相同的规则.

Properties

属性章节必须采用以下形式:

  1. ### session.defaultSession
  2. ...

标题可以是 ### 级别或 #### 级别,具体取决于它是模块还是类的属性。

文档翻译

请参见 electron/i18n