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 del argumento se indica por cualquiera de los primitivos de JavaScript (p. ej. string, Promise, o Object), o una estructura API personalizada de Electron como Cookie, 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.

Traducciones de la documentación​

Ver electron/electron-i18n