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. The type of argument is notated by either JavaScript primitives (e.g. string, Promise, or Object), a custom API structure like Electron's Cookie, or the wildcard 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.

API History​

An "API History" block is a YAML code block encapsulated by an HTML comment that should be placed directly after the Markdown header for a class or method, like so:

#### `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)

Set a custom position for the traffic light buttons. Can only be used with `titleBarStyle` set to `hidden`.

It should adhere to the API History JSON Schema (api-history.schema.json) which you can find in the docs folder. The API History Schema RFC includes example usage and detailed explanations for each aspect of the schema. The purpose of the API History block is to describe when/where/how/why an API was:

  • Añadido
  • Changed (usually breaking changes)
  • Obsoletizado Each API change listed in the block should include a link to the PR where that change was made along with an optional short description of the change. If applicable, include the heading id for that change from the breaking changes documentation. The API History linting script (lint:api-history) validates API History blocks in the Electron documentation against the schema and performs some other checks. You can look at its tests for more details. There are a few style guidelines that aren't covered by the linting script:

Formato​

Always adhere to this format:

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​

  • Use two spaces for indentation.
  • Do not use comments.

Descriptions​

  • Always wrap descriptions with double quotation marks (i.e. "example").
  • Describe the change in a way relevant to app developers and make it capitalized, punctuated, and past tense.
    • Refer to Clerk for examples.
  • Keep descriptions concise.
    • Ideally, a description will match its corresponding header in the breaking changes document.
    • Favor using the release notes from the associated PR whenever possible.
    • Developers can always view the breaking changes document or linked pull request for more details.

Placement​

Generally, you should place the API History block directly after the Markdown header for a class or method that was changed. However, there are some instances where this is ambiguous:

Chromium bump​

Sometimes a breaking change doesn't relate to any of the existing APIs. In this case, it is ok not to add API History anywhere.

Change affecting multiple APIs​

Sometimes a breaking change involves multiple APIs. In this case, place the API History block under the top-level Markdown header for each of the involved APIs.

# 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)

Notice how an API History block wasn't added under:

  • contextBridge.exposeInMainWorld(apiKey, api) since that function wasn't changed, only how it may be used:
  contextBridge.exposeInMainWorld('app', {
-   ipcRenderer,
+   onEvent: (cb) => ipcRenderer.on('foo', (e, ...args) => cb(args))
  })

Traducciones de la documentación​

Ver electron/electron-i18n