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.

Traductions de la documentation

Voir electron/i18n