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​

  • Chaque page doit avoir un seul titre de niveau # au début de la page.
  • Les chapitres d'une même page doivent avoir leur titre au niveau ##.
  • Les sous-chapitres doivent voir le nombre de # de leur titre qui augmentent selon leur niveau d'imbrication.
  • Le titre de la page doit suivre casse de titre APA.
  • Tous les chapitres doivent suivre les règles de phrase APA.

Utilisons Démarrage Rapide comme exemple :

# Démarrage rapide

...

## Processus principal

...

## Processus de rendu

...

## Lancez votre application

...

### Exécuter en tant que distribution

...

### Téléchargement manuel du binaire Electron

...

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

Règles pour le markdown​

Ce dépôt utilise le paquet markdownlint pour imposer un style cohérent au Markdown. Pour les règles exactes, voir le fichier .markdownlint.json dans le dossier racine .

Quelques règles de style non couvertes par les règles du linter :

  • Utilisez sh au lieu de cmd dans les blocs de code (en raison de l'outil de coloration syntaxique).
  • Limiter si possible la longueur des lignes entre 80 et 100 caractères pour des raisons de lisibilité .
  • Les listes ne doivent pas dépasser 2 niveaux (à cause du formatage du markdown).
  • Tous les blocs de code js et javascript sont vérifiés avec le 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​

La doc API de chaque module doit utiliser le nom réel de l'objet retourné par require('electron') comme titre (tel que BrowserWindow, autoUpdater ou session).

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

En prenant session comme exemple :

# session

> Gère les sessions, les cookies, le cache, les paramètres de proxy, etc. du navigateur.

Événements et méthodes des modules​

Pour les modules qui ne sont pas des classes, les méthodes et événements doivent figurer sous les chapitres ## Methods et ## Events.

En prenant autoUpdater comme exemple :

# autoUpdater

## Events

### Event: 'error'

## Methods

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

Classes​

  • Les classes de l'API ou les classes faisant partie de modules doivent être listées sous un chapitre ## Classe: Nom de la Classe.
  • Une page peut avoir plusieurs classes.
  • Les constructeurs doivent être listés avec un titre de niveau ###.
  • Les Méthodes Statiques doivent être listées sous un chapitre ### Méthodes Statiques.
  • Les Méthodes d'instance doivent être listées sous un chapitre ### Méthodes d'Instance.
  • Toutes les méthodes ayant une valeur de retour doivent commencer leur description par "Returns [TYPE] - [Description du retour]"
    • Si la méthode renvoie un Object, la structure de celui-ci peut être spécifiée à l’aide d’un deux-points suivi d’une nouvelle ligne puis d’une liste non ordonnée de propriétés dans le même style que pour les paramètres des fonctions.
  • Les événements d'instance doivent être listés sous un chapitre ### Evénements d'Instance.
  • Les événements d'instance doivent être listés sous un chapitre ###Propriétés d'Instance.
    • Les propriétés d’instance doivent commencer par " Un [Type de propriété] ..."

En prenant comme exemple les classes Session et Cookies :

# 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 - Une description du paramètre.
* `facultatif` Integer(facultatif) - Autre description de paramètre.

...

Niveau de titre​

Le titre peut être de niveau ### ou #### selon qu'il s'agit d'une méthode de module ou de classe.

Signature de fonction​

Pour les modules, le nomObjet est le nom du module. 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.

Par exemple, les méthodes de la classe Session du module session doivent utiliser ses pour le nomObjet.

Les arguments facultatifs sont notés avec des crochets [] entourant l'argument facultatif ainsi qu'une virgule nécessaire si cet argument facultatif suit un autre 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. Le type des arguments est noté soit par une des des primitives JavaScript (par ex. string, Promise ou Object) soit par une structure d'API personnalisée comme Cookied'Electron, ou le joker any.

Si l'argument est de type Array, utiliser le raccourci [] avec le type de valeur à l'intérieur du tableau (par exemple,any[] ou string[]).

Si l’argument est de type Promise, paramétrez le type avec ce que la promesse résout (par exemple, Promise<void> ou Promise<string>).

Si un argument peut être de plusieurs types, séparez les types par |.

La description des arguments de type Function doivent clairement expliquer comment elle peut être appelée et lister les types des paramètres qui lui sont transmis.

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. Les valeurs peuvent être macOS, Windows ou 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

...

Le titre peut être au niveau ### ou #### selon qu'il s'agit d'un événement d'un module ou d'une classe.

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

...

Le titre peut être au niveau ### ou #### selon qu'il s'agit d'une propriété de classe ou de module.

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](latest/api/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    |  <!--
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](latest/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​

Voir electron/i18n