Ir para o conteúdo principal

Guia de estilo de Documentação do Electron

Estas são as diretrizes para escrever a documentação do Electron.

Títulos​

  • Cada página deve ter um único # no nível de título na parte superior.
  • Capítulos na mesma página devem ter títulos de nível ##.
  • Subcapítulos precisam de aumentar o numero de # no título de acordo com o seu nível de profundidade de aninhamento.
  • O título da página deve seguir a Caixa de título da APA.
  • Todos os capítulos devem seguir a caixa de frases da APA.

Usado o Inicio Rápido como exemplo:

# Início Rápido

...

## Main process

...

## Processo de Renderização

...

## Executar seu 'app'

...

### Run as a distribution

...

### Manually downloaded Electron binary

...

Para referencias à API, existem exceções a está regra.

Funcionalidades Markdown​

Esse repositório usa o pacote markdownlint para impor consistência de estilização de Markdown. Para obter as regras exatas, consulte o arquivo .markdownlint.json na pasta raiz.

Existem algumas diretrizes de estilo que não estão cobertas pelas regras do linter:

  • Use sh ao invés de cmd nos blocos de código (devido ao destaque de sintaxe).
  • Mantenha os comprimentos de linha entre 80 e 100 caracteres, se possível, para fins de leitura.
  • No nesting lists more than 2 levels (due to the markdown renderer).
  • All js and javascript code blocks are linted with standard-markdown.
  • Para listas não ordenadas, use asteriscos em vez de traços.

Picking words​

  • Use "will" over "would" when describing outcomes.
  • Prefer "in the ___ process" over "on".

Referências da API​

The following rules only apply to the documentation of APIs.

Título e descrição​

Cada documentação de módulos da API deve usar o nome real do objeto retornado por require('electron') como seu título (como BrowserWindow, autoUpdater, e session).

Diretamente abaixo do título da página, adicione uma descrição de uma linha do módulo como uma citação de markdown (começando com >).

Usando o módulo session como exemplo:

# session

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

Métodos e eventos de módulo​

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

## Events

### Event: 'error'

## Methods

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

Classes​

  • API classes or classes that are part of modules must be listed under a ## Class: TheClassName chapter.
  • One page can have multiple classes.
  • Construtores devem ser listados com títulos de nível ###.
  • Métodos Estáticos devem ser listados em um capítulo ### Métodos Estáticos.
  • Métodos de Instância devem ser listados em um capítulo ### Métodos de Instância.
  • All methods that have a return value must start their description with "Returns [TYPE] - [Return description]"
    • Se o método retornar um Object, sua estrutura pode ser especificada usando dois pontos seguidos de uma nova linha, em seguida, uma lista de propriedades não ordenadas no mesmo estilo que parâmetros de função.
  • Los Eventos de Instancia deben aparecer listados bajo un capítulo de ### Eventos de Instancia.
  • Propriedades da Instância devem ser listadas em um capítulo ### Propriedades da Instância.
    • Instance Properties must start with "A [Property Type] ..."

Usando as classes Session e Cookies como exemplo:

# session

## Métodos

### session.fromPartition(partition)

## Propriedades Estáticas

### session.defaultSession

## Classe: Session

### Eventos de Instância

#### Event: 'will-download'

### Métodos de Instância

#### `ses.getCacheSize()`

### Propriedades de Instância

#### `ses.cookies`

## Classe: Cookies

### Métodos de Instância

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

Métodos e seus argumentos​

O capítulo de métodos deve estar no seguinte formato:

### 'objectName.methodName(necessario[, opcional]))

* 'necessário' string - Uma descrição do parâmetro.
* 'opcional' Integer (opcional) - Outra descrição do parâmetro.

...

Nível de cabeçalho​

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

Function signature​

For modules, the objectName is the module's name. For classes, it must be the name of the instance of the class, and must not be the same as the module's name.

Por exemplo, os métodos da classe Session sob o módulo session usa ses como 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:

obrigatório[, opcional]

Argument descriptions​

More detailed information on each of the arguments is noted in an unordered list below the method. 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>).

If an argument can be of multiple types, separate the types with |.

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.

Platform-specific functionality​

Se um argumento ou um método for exclusivo para determinadas plataformas, essas plataformas são denotadas usando uma lista itálica delimitada pelo espaço seguindo o tipo de dados. Os valores podem ser macOS, Windows ou Linux.

* `animate` boolean (optional) _macOS_ _Windows_ - Animate the thing.

Eventos​

O capítulo de eventos deve estar na seguinte forma:

### Event: 'wake-up'

Returns:

* `time` string

...

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

Os argumentos de um evento seguem as mesmas regras e métodos.

Propriedades​

O capítulo de propriedades deve estar no seguinte formulário:

### session.defaultsession

...

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

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:

  • Adicionado
  • Changed (usually breaking changes)
  • Obsoleto 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))
  })

Documentation translations​

Veja electron/i18n