跳至主要内容

Electron 的 API 文档作为结构化数据

·阅读时长 3 分钟
zeke
zeke

今天，我们宣布对 Electron 的文档进行一些改进。每个新版本现在都包含一个 JSON 文件，该文件详细描述了 Electron 的所有公共 API。我们创建此文件是为了让开发人员能够以有趣的新方式使用 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://www.electron.js.cn/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 风格指南，因此其内容可以以编程方式解析。

The electron-docs-linter 是 electron/electron 存储库的一个新的开发依赖项。它是一个命令行工具，用于检查所有 Markdown 文件并强制执行风格指南的规则。如果发现错误，则会列出错误并停止发布过程。如果 API 文档有效，则会创建 electron-json.api 文件并作为 Electron 版本的一部分 上传到 GitHub。

标准 Javascript 和标准 Markdown​

今年早些时候，Electron 的代码库已更新为对所有 JavaScript 使用 standard 规范检查器。Standard 的自述文件总结了此选择背后的原因

采用标准风格意味着将代码清晰度和社区惯例的重要性置于个人风格之上。这可能并不适用于 100% 的项目和开发文化，但是开源对于新手来说可能是一个充满敌意的场所。设定明确的、自动化的贡献者期望值可以使项目更健康。

我们最近还创建了 standard-markdown 来验证我们文档中的所有 JavaScript 代码段是否有效且与代码库本身的风格一致。

这些工具共同帮助我们使用持续集成 (CI) 自动查找拉取请求中的错误。这减少了人工代码审查的负担，并让我们对文档的准确性更有信心。

社区的努力​

Electron 的文档在不断改进，我们感谢我们优秀的开源社区为此做出的贡献。在撰写本文时，近 300 人为文档做出了贡献。

我们很高兴看到人们如何使用这些新的结构化数据。可能的用途包括