Today we're announcing some improvements to Electron's documentation. Every new release now includes a JSON file that describes all of Electron's public APIs in detail. We created this file to enable developers to use Electron's API documentation in interesting new ways.
Each API is an object with properties like name, description, type, etc. Classes such as
Menu have additional properties describing their instance methods, instance properties, instance events, etc.
Here's an excerpt from the schema that describes the
description: 'Create and control browser windows.',
And here's an example of a method description, in this case the
apis.BrowserWindow.instanceMethods.setMaximumSize instance method:
signature: '(width, height)',
description: 'Sets the maximum size of window to width and height.',
Using the new data
To make it easy for developers to use this structured data in their projects, we've created electron-docs-api, a small npm package that is published automatically whenever there's a new Electron release.
npm install electron-api-docs --save
For instant gratification, try out the module in your Node.js REPL:
npm i -g trymodule && trymodule electron-api-docs=apis
How the data is collected
The electron-docs-linter is a new development dependency of the
electron/electron repository. It is a command-line tool that lints all the markdown files and enforces the rules of the styleguide. If errors are found, they are listed and the release process is halted. If the API docs are valid, the
electron-json.api file is created and uploaded to GitHub as part of the Electron release.
Earlier this year, Electron's codebase was updated to use the
Adopting standard style means ranking the importance of code clarity and community conventions higher than personal style. This might not make sense for 100% of projects and development cultures, however open source can be a hostile place for newbies. Setting up clear, automated contributor expectations makes a project healthier.
Together these tools help us use continuous integration (CI) to automatically find errors in pull requests. This reduces the burden placed on humans doing code review, and gives us more confidence about the accuracy of our documentation.
A community effort
Electron's documentation is constantly improving, and we have our awesome open-source community to thank for it. As of this writing, nearly 300 people have contributed to the docs.
We're excited to see what people do with this new structured data. Possible uses include: