跳转到主内容

结构化数据式的Electron API文档

· 阅读时间：约 5 分钟
zeke

今天我们正式宣布对Electron文档的一些改进。 现在，每个新的发布版本都将包括一份对Electron公共API详细描述的JSON文件 我们创建该文件，以此让开发者能够用新潮有趣的方式来访问Electron的API文档。

架构概述​

每个 API 都是一个对象，具有名称、描述、类型等属性。 BrowserWindow 和 Menu 类具有描述其实例方法、实例属性、实例事件等 附加属性。

下面是描述 BrowserWindow 类的架构摘录：

{
  name: 'BrowserWindow',
  description: 'Create and control browser windows.',
  process: {
    main: true,
    renderer: false
  },
  type: 'Class',
  instanceName: 'win',
  slug: 'browser-window',
  websiteUrl: 'https://electronjs.org/docs/api/browser-window',
  repoUrl: 'https://github.com/electron/electron/blob/v1.4.0/docs/api/browser-window.md',
  staticMethods: [...],
  instanceMethods: [...],
  instanceProperties: [...],
  instanceEvents: [...]
}
}

下面是一个方法描述的示例，在本例中为 apis.BrowserWindow.instanceMethods.setMaximumSize 实例方法：

{
  name: 'setMaximumSize',
  signature: '(width, height)',
  description: 'Sets the maximum size of window to width and height.',
  parameters: [{
    name: 'width',
    type: 'Integer'
  }, {
    name: 'height',
    type: 'Integer'
  }]
}

使用新数据​

为了让开发人员能够轻松地在他们的项目中使用这些结构化数据， 我们创建了 electron-docs-api，一个小型 npm包，每当有新的Electron 发布时，它都会自动发布。

npm install electron-api-docs --save

为了及时尝试，请尝试Node.js REPL中的模块：

npm i -g trymodule && trymodule electron-api-docs=apis

如何收集数据​

Electron的API文档遵循 Electron 编码风格 和 Electron 风格指南， 因此其内容可以通过编程方式解析。

electron-docs-linter 是 electron/electron 库的新开发依赖项。 它是一个命令行工具，会校验所有Markdown文件并强制执行styleguid中的规则。 如果发现错误，则会列出这些错误，并暂停发布 过程。 如果 API 文档有效，则会创建 electron-json.api 文件 ，并作为 Electron 版本的一部分上传到 GitHub。

标准 Javascript 和标准 Markdown​

今年早些时候，Electron的代码库进行了更新，以在所有JavaScript中使用 standard 代码纠错工具（linter）。 Standard的 README文件总结了这一选择背后的原因：

采用标准风格意味着代码清晰度和社区约定的重要性比个人风格更高。 也许这对所有项目和发展文化来说是难以理解的，但对新手来说开源可能是一个令人生畏的地方。 设定明确、自动的代码贡献者期望能使一个项目更加健康。

我们最近还创建了[standard-markdown](https://github. com/zeke/standard-markdown) ，以验证文档中所有JavaScript代码片段是否有效且与代码库本身的样式一致。

这些工具一起帮助我们使用连续集成 (CI) 来自动找到 拉取请求（Pull Request）中的错误。 这减轻了人类在代码 审查方面的负担，并使我们对文档的准确性更有信心。

社区的努力​

因我们可敬的开源社区的不懈努力，Electron的文档在不断改进。 在撰写本文时， 近300人为文档做出了贡献。

我们很期待看到人们如何处理这个新的结构化数据。 可能的用途包括：