Aller au contenu principal

Règles de style pour la documentation d'Electron

Lignes directrices pour la rédaction de la documentation d'Electron.

Titres​

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

# Démarrage Rapide

...

## Principal processus

...

## Processus de rendu

...

## Exécuter votre application

...

### Exécuter en tant que distribution

...

### Executable d'Electron téléchargé manuellement

...

Il existe des exceptions à cette règle dans le cas de références de l'API.

Règles pour le 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.

Quelques règles de style non couvertes par les règles du 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.
  • Les listes ne doivent pas dépasser 2 niveaux (à cause du formatage du markdown).
  • All js and javascript code blocks are linted with standard-markdown.
  • Pour les listes non ordonnées, utilisez des astérisques plutôt que des tirets.

Choix des mots​

  • Utilisez "sera" au lieu de "devrait" pour décrire des résultats.
  • Préférez « dans le processus de ___ » au lieu de « sur ».

Références de l'API​

Les règles suivantes s'appliquent uniquement à la documentation des APIs.

Titre et description​

Each module's API doc must use the actual object name returned by require('electron') as its title (such as BrowserWindow, autoUpdater, and session).

Directement sous le titre de la page, ajouter une ligne de description du module comme une citation markdown (commençant par >).

Using the session module as an example:

# session

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

Événements et méthodes des modules​

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.
  • Une page peut avoir plusieurs classes.
  • 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.
    • Les propriétés d’instance doivent commencer par " Un [Type de propriété] ..."

Using the Session and Cookies classes as an example:

# session

## Méthodes

### session.fromPartition(partition)

## Propriétés Statiques

### session.defaultSession

## Classe : Session

### Événements d'instance

#### Événement : 'will-download'

### Méthodes d'instance

#### `ses.getCacheSize()`

### Propriétés d'instance

#### `ses.cookies`

## Classe : Cookies

### Méthodes d'instance

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

Méthodes et leurs arguments​

Le chapitre sur les méthodes doit respecter la forme suivante :

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

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

...

Niveau de titre​

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

Signature de fonction​

For modules, the objectName is the module's name. Pour les classes, ce doit être le nom de l'instance de la classe, et ne doit pas être le même que le nom du module.

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:

required[, facultatif]

Descriptions des arguments​

Des informations plus détaillées sur chacun des arguments sont notées dans une liste non ordonnée en dessous de la méthode. 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 argument peut être de plusieurs types, séparez les types par |.

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.

Fonctionnalité spécifique à la plateforme​

Si un argument ou une méthode est propre à certaines plateformes, ces plateformes sont listés en italique après le type de données. Values can be macOS, Windows or Linux.

* `animate` boolean (optional) _macOS_ _Windows_ - Anime la chose.

Événements​

Le chapitre sur les événements doit être sous la forme suivante :

### Event: 'wake-up'

Returns:

* `time` string

...

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

Les arguments d'un événement suivent les mêmes règles que pour les méthodes.

Propriétés​

Le chapitre des propriétés doit être sous la forme suivante :

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

  • Added
  • Changed (usually breaking changes)
  • Deprecated

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:

Format​

Always adhere to this format:

API HEADER | #### win.flashFrame(flag) BLANK LINE | HTML COMMENT OPENING 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))
  })

Traductions de la documentation​

See electron/i18n