Saltar al contenido principal

Guía de estilo de documentación Electron

Estas son las directrices para escribir documentación de Electron.

Encabezados​

  • Cada página debe tener un solo título de nivel # al principio.
  • Los capítulos en la misma pagina deben tener títulos de nivel ##.
  • Los sub-capítulos necesitan incrementar el numero de # en el encabezado de acuerdo al su profundidad de anidamiento.
  • El titulo de la pagina debe seguir el Estilo APA.
  • Todos los capítulos deben seguir el Estilo APA .

Usando Quick Start como ejemplo:

# Inicio rápido

...

## Proceso principal

...

## Proceso Renderer

...

## Ejecuta tu aplicación

...

### Ejecuta como una distribución

...

### Binario Electron descargado manualmente

...

Para referencias API, hay excepciones para esta regla.

Reglas de Markdown​

Este repositorio usa el paquete markdownlint para hacer cumplir un estilo Markdown coherente. Para las reglas exactas, vea el archivo .markdownlint.json en la carpeta raíz.

Hay algunas pautas de estilo que no están cubiertas por las reglas del linter:

  • Usa sh en vez de cmd en code blocks (debido al resaltador de sintaxis).
  • Mantén la longitud de las líneas entre 80 y 100 caracteres si es posible para fines de legibilidad.
  • No anidar listas de más de 2 niveles (debido al renderizador markdown).
  • Todos los bloques de código js y javascript están analizados con standard-markdown.
  • Para listas no ordenadas, use asteriscos en lugar de guiones.

Escoger palabras​

  • Utilice "podrá" en vez de "podría" al describir resultados.
  • Prefiere "en el ___ proceso" sobre "en".

Referencias API​

Las siguientes reglas sólo se aplican a la documentación de APIs.

Titulo y descripción​

El documento API de cada módulo debe usar el nombre real del objeto devuelto por require('electron') como título (como BrowserWindow, autoUpdater, y session).

Directamente bajo el título de la página, agregue una línea de descripción del módulo como una cita markdown (comenzando con >).

Usando el módulo session como un ejemplo:

# session

> Administra sesiones de navegador, cookies, caché, configuración del proxy, etc.

Métodos del módulo y eventos​

Para módulos que no son clases, sus métodos y los eventos deben esar listados bajo los capítulos ## Métodos y ## Eventos.

Usando autoUpdater como ejemplo:

# autoUpdater

## Eventos

### Evento: 'error'

## Métodos

### `autoUpdater.setFeedURL(url[, requestHeaders])`

Clases​

  • Las clases API o las clases que forman parte de los módulos también deben ser listadas bajo el capítulo ## clase: TheClassName.
  • Una página puede tener múltiples clases.
  • Los constructores deben ser listados con los encabezados de nivel ###.
  • Los Métodos Estáticos deben ser listados bajo un capítulo ### Métodos Estáticos.
  • Los Métodos de Instancia deben ser listados bajo un capítulo ### Métodos de Instancia.
  • Todos los métodos que tienen un valor de retorno deben comenzar su descripción con "Returns [TYPE] - [Devuelve descripción]"
    • Si el método devuelve un Object, su estructura puede ser especificada usando dos puntos, seguido por una línea, luego una lista desordenada de propiedades en el mismo estilo que parametros de función.
  • Los Eventos de Instancia deben aparecer listados bajo un capítulo de ### Eventos de Instancia.
  • Las Propiedades de Instancia deben ser listadas bajo un capitulo ### Instance Properties.
    • Las Propiedades de Instancia deben comenzar con "A [Tipo de propiedad] ..."

Usando las clases Session y Cookies como ejemplo:

# session

## Methods

### session.fromPartition(partition)

## Static Properties

### session.defaultSession

## Class: Session

### Instance Events

#### Event: 'will-download'

### Instance Methods

#### `ses.getCacheSize()`

### Instance Properties

#### `ses.cookies`

## Class: Cookies

### Instance Methods

#### `cookies.get(filter, callback)`

Métodos y sus argumentos​

El capítulo de métodos debe estar de la siguiente forma:

### `nombreDeObjeto.nombreDeMétodo(requiredo[, opcional]))`

* `requerido` string - Una descripción del parámetro.
* `opcional` Integer (opcional) - Otra descripción del parámetro.

...

Nivel del encabezado​

El encabezado puede ser de nivel ### o #### dependiendo si el método pertenece a un módulo o una clase.

Firma de la función​

Para módulos, el objectName es el nombre del módulo. Para las clases debe ser el nombre de la instancia de la clase y no debe ser el mismo nombre del módulo.

Por ejemplo, los métodos de la clase Session bajo el módulo session deben usar ses como el objectName.

Los argumentos opcionales se indican entre corchetes [] rodeando el argumento opcional así como la coma requerida si este argumento opcional sigue a otro argumento:

requerido[, opcional]

Descripciones del argumento​

La información más detallada sobre cada uno de los argumentos se indica en una lista desordenada debajo del método. El tipo de argumento se anota mediante primitivas de JavaScript (por ejemplo, string, Promise u Object), una estructura de API personalizada como Cookie de Electron o el comodín any.

Si el argumento es de tipo Array, use la abreviatura [] con el tipo de valor dentro del array (por ejemplo,any[] o string[]).

Si el argumento es de tipo Promise, parametrizar el tipo con el que la promesa resuelve (por ejemplo, Promise<void> o Promise<string>).

Si un argumento puede ser de varios tipos, separe los tipos con |.

La descripción para los argumentos de tipo Function deben dejar en claro cómo podrían ser llamados y la lista de tipos de parámetros que se le serán pasados.

Funcionalidad específica de la plataforma​

Si un argumento o un método es único para ciertas plataformas, esas plataformas son denotadas usando una lista con espacio delimitado y en cursiva siguiendo el tipo de data. Los valores pueden ser macOS, Windows, o Linux.

* `animate` boolean (opcional) _macOS_ _Windows_ - Anima la cosa.

Eventos​

El capítulo de eventos debe estar de la siguiente forma:

### Evento: 'wake-up'

Devuelve:

* `time` string

...

El encabezado puede ser de nivel ### o #### dependiendo si el evento pertenece a un módulo o a una clase.

Los argumentos de un evento siguen las mismas reglas que los métodos.

Propiedades​

El capítulo de propiedades debe estar de la siguiente forma:

### session.defaultSession

...

El encabezado puede ser de nivel ### o #### dependiendo si la propiedad pertenece al módulo o la una clase.

Historial de API​

Un bloque de "Historial de API" es un bloque de código YAML encapsulado por un comentario HTML que debe colocarse directamente después del encabezado Markdown de una clase o método, de la siguiente manera:

#### `win.setTrafficLightPosition(position)` _macOS_

<!--
```YAML history
added:
  - pr-url: https://github.com/electron/electron/pull/22533
changes:
  - pr-url: https://github.com/electron/electron/pull/26789
    description: "Made `trafficLightPosition` option work for `customButtonOnHover` window."
deprecated:
  - pr-url: https://github.com/electron/electron/pull/37094
    breaking-changes-header: deprecated-browserwindowsettrafficlightpositionposition
```
-->

* `position` [Point](structures/point.md)

Establece una posición personalizada para los botones del semáforo. Solo se puede utilizar con `titleBarStyle` establecido en `hidden`.

Debe cumplir con el historial de API Esquema JSON (api-history.schema.json) que puede encontrar en la carpeta docs. El RFC del esquema de historial de API incluye ejemplos de uso y explicaciones detalladas de cada aspecto del esquema. El propósito del bloque Historial de API es describir cuándo/dónde/cómo/por qué una API fue:

  • Añadido
  • Cambiado (normalmente cambios importantes)
  • Obsoletizado Cada cambio de API que se incluya en el bloque debe incluir un enlace a la publicación de relaciones públicas donde se realizó ese cambio junto con una breve descripción opcional del cambio. Si corresponde, incluya el ID de encabezado para ese cambio desde la documentación de cambios importantes. El script de linting del historial de API (lint:api-history) valida los bloques del historial de API en la documentación de Electron contra el esquema y realiza otras comprobaciones. Puede consultar sus tests para más detalles. Hay algunas pautas de estilo que no están cubiertas por el script de linting:

Formato​

Siga siempre este formato:

API HEADER                  |  #### `win.flashFrame(flag)`
BLANK LINE                  | 
HTML COMMENT OPENING TAG    |  <!--
API HISTORY OPENING TAG     |  ```YAML history
API HISTORY                 |  added:
                            |    - pr-url: https://github.com/electron/electron/pull/22533
API HISTORY CLOSING TAG     |  ```
HTML COMMENT CLOSING TAG    |  -->
BLANK LINE                  |

YAML​

  • Utilice dos espacios para la sangría (indentación).
  • No utilice comentarios.

Descripciones​

  • Envuelva siempre las descripciones entre comillas dobles (por ejemplo, "ejemplo").
  • Describe el cambio de una manera que sea relevante para los desarrolladores de aplicaciones y hazlo con mayúscula, puntuación y en tiempo pasado.
    • Consulte Clerk para ver ejemplos.
  • Mantenga las descripciones concisas.
    • Lo ideal es que la descripción coincida con su encabezado correspondiente en el documento de cambios importantes.
    • Siempre que sea posible, es recomendable utilizar las notas de la versión de PR asociada.
    • Los desarrolladores siempre pueden consultar el documento de cambios importantes o la solicitud de extracción vinculada para obtener más detalles.

Colocación​

En general, debes colocar el bloque Historial de API directamente después del encabezado Markdown para una clase o método que se modificó. Sin embargo, hay algunos casos en los que esto es ambiguo:

Chromium bump​

A veces, un cambio importante no está relacionado con ninguna de las API existentes. En este caso, está bien no agregar el historial de API en ningún lugar.

Cambio que afecta a múltiples API​

A veces, un cambio importante (breaking change) involucra múltiples API. En este caso, coloque el bloque Historial de API debajo del encabezado Markdown de nivel superior para cada una de las API involucradas.

# contextBridge

<!--
```YAML history
changes:
  - pr-url: https://github.com/electron/electron/pull/40330
    description: "`ipcRenderer` can no longer be sent over the `contextBridge`"
    breaking-changes-header: behavior-changed-ipcrenderer-can-no-longer-be-sent-over-the-contextbridge
```
-->

> Create a safe, bi-directional, synchronous bridge across isolated contexts
# ipcRenderer

<!--
```YAML history
changes:
  - pr-url: https://github.com/electron/electron/pull/40330
    description: "`ipcRenderer` can no longer be sent over the `contextBridge`"
    breaking-changes-header: behavior-changed-ipcrenderer-can-no-longer-be-sent-over-the-contextbridge
```
-->

Process: [Renderer](../glossary.md#renderer-process)

Observe cómo no se agregó un bloque de Historial de API en:

  • contextBridge.exposeInMainWorld(apiKey, api) dado que esa función no se modificó, solo se modificó cómo se puede utilizar:
  contextBridge.exposeInMainWorld('app', {
-   ipcRenderer,
+   onEvent: (cb) => ipcRenderer.on('foo', (e, ...args) => cb(args))
  })

Traducciones de la documentación​

Ver electron/electron-i18n