Saltar al contenido principal

Documentos de la API de Electron como Datos Estructurados

· 4 lectura mínima
zeke
zeke

Hoy presentamos algunas mejoras en la documentación de Electron. Cada nuevo lanzamiento ahora incluye un archivo JSON que describe todas las APIs públicas de Electron en detalle. Hemos creado este archivo para facilitar a los desarrolladores usar la documentación de la API de Electron de maneras nuevas e interesantes.

Resumen del esquema​

Cada API es un objeto con propiedades como nombre, descripción, tipo, etc. Las clases como BrowserWindow y Menu tienen propiedades adicionales que describen sus métodos de instancia, propiedades de instancia, eventos de instancia, etc.

Aquí hay un fragmento del esquema que describe la clase BrowserWindow:

{
  name: 'BrowserWindow',
  description: 'Crear y controlar ventanas del navegador. ,
  process: {
    main: true,
    renderer: false
  },
  type: 'Class',
  instanceName: 'win',
  slug: 'browser-window',
  websiteUrl: 'https://electronjs. rg/docs/api/browser-window',
  repoUrl: 'https://github.com/electron/electron/blob/v1.4.0/docs/api/browser-window. d',
  staticMethods: [...],
  instanceMethods: [...],
  instanceProperties: [...],
  instanceEvents: [...]
}
}

Y aquí hay un ejemplo de la descripción de un método, en este caso el método de instancia apis.BrowserWindow.instanceMethods.setMaximumSize:

{
  name: 'setMaximumSize',
  signature: '(width, height)', 
  description: 'Establece el tamaño máximo de la ventana a anchura y altura. ,
  parameters: [{
    name: 'width',
    type: 'Integer'
  }, {
    name: 'height',
    type: 'Integer'
  }]
}

Usando los nuevos datos​

Para facilitar a los desarrolladores el uso de estos datos estructurados en sus proyectos, hemos creado electron-docs-api, un pequeño paquete npm que se publica automáticamente cada vez que hay una nueva versión de Electron.

npm install electron-api-docs --save

Para una gratificación instantánea, pruebe el módulo en su REPL de Node.js:

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

Qué datos se recopilan​

La documentación de la API de Electron se adhiere al Estilo de codificación de Electrón y al Estilo de Electrón, para que su contenido pueda ser analizado programáticamente.

El repositorio electron-docs-linter es una nueva dependencia de desarrollo del repositorio electron/electron. Es una herramienta de línea de comandos que muestra todos los archivos de markdown e impone la reglas del styleguide. Si se encuentran errores, se listan y el proceso de liberación se detiene. Si los documentos de la API son válidos, el archivo electron-json.api se crea y se sube a GitHub como parte de la versión de Electron.

Javascript estándar y Markdown estándar​

A principios de este año, el código base de Electron fue actualizado para usar el linter standard para todos los JavaScript. El README de standard resume el razonamiento detrás de esta elección:

Adoptar el estilo standard significa clasificar la importancia de la claridad del código y las convenciones comunitarias por encima del estilo personal. Esto podría no tener sentido para el 100% de los proyectos y las culturas de desarrollo, sin embargo el código abierto puede ser un lugar hostil para los novatos. Establecer expectativas claras y automatizadas de los colaboradores hace que un proyecto sea más saludable.

También recientemente creamos standard markdown para verificar que todos los fragmentos de código JavaScript en nuestra documentación son válidos y consistentes con el estilo en la base de código.

Juntas, estas herramientas nos ayudan a utilizar la integración continua (IC) para encontrar automáticamente errores en las solicitudes PR para añadir actualizaciones al repositorio (Pull Requests). Esto reduce la carga impuesta a los humanos haciendo revisión del código, y nos da más confianza sobre la precisión de nuestra documentación.

Un esfuerzo de la comunidad​

La documentación de Electron está mejorando constantemente, y tenemos a nuestra increíble comunidad de código abierto a la que darle las gracias por ello. Cerca de 300 personas han contribuido a la documentación, que incluye este texto.

Estamos encantados de ver qué hacen las personas con estos nuevos datos estructurados. Las usos posibles incluyen: