メインコンテンツにスキップ

構造化データとしての Electron の API ドキュメント

·読了時間 3分
zeke
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://electron.dokyumento.jp/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 の新しいリリースがあるたびに自動的に公開される小さな npm パッケージである electron-docs-api を作成しました。

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 リポジトリの新しい開発依存関係です。これは、すべてのマークダウンファイルを lint し、スタイルガイドのルールを適用するコマンドラインツールです。エラーが見つかった場合は、それらがリストされ、リリースプロセスは停止します。API ドキュメントが有効な場合、electron-json.api ファイルが作成され、Electron リリースの一部として GitHub にアップロード されます。

標準 JavaScript と標準 Markdown​

今年初め、Electron のコードベースは、すべての JavaScript に standard linter を使用するように更新されました。Standard の README は、この選択の理由を次のようにまとめています。

標準スタイルを採用することは、コードの明確さとコミュニティの慣習の重要性を、個人のスタイルよりも高く評価することを意味します。これは、すべてのプロジェクトと開発文化に当てはまるとは限りませんが、オープンソースは初心者にとって厳しい場所になる可能性があります。明確で自動化された貢献者への期待を設定することで、プロジェクトはより健全になります。

また、最近 standard-markdown を作成して、ドキュメント内のすべての JavaScript コードスニペットが有効であり、コードベース自体のスタイルと一致していることを確認しました。

これらのツールを組み合わせることで、継続的インテグレーション (CI) を使用してプルリクエストのエラーを自動的に見つけることができます。これにより、コードレビューを行う人間の負担が軽減され、ドキュメントの正確性についてより自信を持つことができます。

コミュニティの取り組み​

Electron のドキュメントは常に改善されており、素晴らしいオープンソースコミュニティに感謝しています。これを書いている時点で、約 300 人がドキュメントに貢献しています。

この新しい構造化データで人々が何をするのか、楽しみにしています。考えられる用途は次のとおりです。