Saltar al contenido principal

Guía de estilo de documentación Electron

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

Encabezados​

  • Each page must have a single #-level title at the top.
  • Chapters in the same page must have ##-level headings.
  • Sub-chapters need to increase the number of # in the heading according to their nesting depth.
  • The page's title must follow APA title case.
  • All chapters must follow APA sentence case.

Using Quick Start as example:

# Inicio Rápido

...

## Proceso principal

...

## Proceso de renderizado

...

## Ejecutar tu aplicación

...

### Ejecutar como distribución

...

### Programa binario de Electron descargado manualmente

...

Para referencias API, hay excepciones para esta regla.

Reglas de Markdown​

This repository uses the markdownlint package to enforce consistent Markdown styling. For the exact rules, see the .markdownlint.json file in the root folder.

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

  • Use sh instead of cmd in code blocks (due to the syntax highlighter).
  • Keep line lengths between 80 and 100 characters if possible for readability purposes.
  • No anidar listas de más de 2 niveles (debido al renderizador markdown).
  • All js and javascript code blocks are linted with 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​

Each module's API doc must use the actual object name returned by require('electron') as its title (such as BrowserWindow, autoUpdater, and 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 >).

Using the session module as an example:

# session

> Manage browser sessions, cookies, cache, proxy settings, etc.

Métodos del módulo y eventos​

For modules that are not classes, their methods and events must be listed under the ## Methods and ## Events chapters.

Using autoUpdater as an example:

# autoUpdater

## Eventos

### Evento: 'error'

## Métodos

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

Clases​

  • API classes or classes that are part of modules must be listed under a ## Class: TheClassName chapter.
  • Una página puede tener múltiples clases.
  • Constructors must be listed with ###-level headings.
  • Static Methods must be listed under a ### Static Methods chapter.
  • Instance Methods must be listed under an ### Instance Methods chapter.
  • All methods that have a return value must start their description with "Returns [TYPE] - [Return description]"
    • If the method returns an Object, its structure can be specified using a colon followed by a newline then an unordered list of properties in the same style as function parameters.
  • Instance Events must be listed under an ### Instance Events chapter.
  • Instance Properties must be listed under an ### Instance Properties chapter.
    • Las Propiedades de Instancia deben comenzar con "A [Tipo de propiedad] ..."

Using the Session and Cookies classes as an example:

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

### `objectName.methodName(required[, optional]))`

* `required` string - A parameter description.
* `optional` Integer (optional) - Another parameter description.

...

Nivel del encabezado​

The heading can be ### or ####-levels depending on whether the method belongs to a module or a class.

Firma de la función​

For modules, the objectName is the module's name. Para las clases debe ser el nombre de la instancia de la clase y no debe ser el mismo nombre del módulo.

For example, the methods of the Session class under the session module must use ses as the objectName.

Optional arguments are notated by square brackets [] surrounding the optional argument as well as the comma required if this optional argument follows another argument:

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.

If the argument is of type Array, use [] shorthand with the type of value inside the array (for example,any[] or string[]).

If the argument is of type Promise, parametrize the type with what the promise resolves to (for example, Promise<void> or Promise<string>).

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

The description for Function type arguments should make it clear how it may be called and list the types of the parameters that will be passed to it.

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. Values can be macOS, Windows or 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

...

The heading can be ### or ####-levels depending on whether the event belongs to a module or a class.

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

...

The heading can be ### or ####-levels depending on whether the property belongs to a module or a class.

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)

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.

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. 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.

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 | 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 the change in a way relevant to app developers and make it capitalized, punctuated, and past tense.
    • Refer to Clerk for examples.
  • Mantenga las descripciones concisas.
    • Ideally, a description will match its corresponding header in the breaking changes document.
    • Siempre que sea posible, es recomendable utilizar las notas de la versión de PR asociada.
    • Developers can always view the breaking changes document or linked pull request for more details.

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​

See electron/i18n