Zum Hauptteil springen

Electron Documentation Style Guide

Dies sind die Richtlinien für das Schreiben von Dokumentation zu Elektron.

Überschriften​

  • Jede Seite hat ein einzelnen Titel mit # am Anfang.
  • Kapitel der selben Seite müssen ##-Level Titel haben.
  • Unterkapitel müssen die Anzahl der # im Titel entsprechend ihrer Schachtelungstiefe erhöhen.
  • Der Titel der Seite muss APA-Titel folgen.
  • Alle Kapitel müssen APA-Satz-Fall folgen.

Am Beispiel von Schnellstart:

# Schnellstart

...

## Main-Prozess

...

## Renderer-Prozess

...

## Ihre App ausführen

...

### Als Distribution ausführen

...

### Electron-Binärdatei manuell herunterladen

...

Für API-Referenzen gibt es Ausnahmen von dieser Regel.

Markdown-Dateien​

Dieses Repository verwendet das markdownlint Paket, um konsistente Markdown-Stils zu erzwingen. Die genauen Regeln finden Sie in der .markdownlint.json -Datei im Stammordner.

Es gibt einige Stilrichtlinien, die nicht von den Linter-Regeln abgedeckt werden:

  • Verwenden Sie sh anstelle von cmd in Codeblöcken (aufgrund des Syntax-Highlighters).
  • Halten Sie die Zeilenlängen möglichst zwischen 80 und 100 Zeichen, um die Lesbarkeit zu gewährleisten.
  • Keine Verschachtelung listet mehr als 2 Ebenen auf (aufgrund des Markdown-Renderers).
  • Alle js- und javascript -Codeblöcke sind mit Standard-Markdown-versehen.
  • Verwenden Sie bei ungeordneten Listen Sternchen anstelle von Bindestrichen.

Wörter auswählen​

  • "Wird" sollte statt "würde" verwendet werden, um Ergebnisse zu beschreiben.
  • Debuggen des Hauptprozesses in VSCode".

API Referenzen​

Die folgenden Regeln gelten nur für Dokumentationen der APIs.

Titel und Beschreibung​

Jede Seite muss den tatsächlichen Objektnamen verwenden, den require('electron') als Titel zurück gibt, wie BrowserWindow, autoUpdater, und session.

Fügen Sie direkt unter dem Seitentitel eine einzeilige Beschreibung des Moduls als Markdown-Zitat hinzu (beginnend mit >).

Am Beispiel des session -Moduls:

# session

> Verwalte Browser-Sitzungen, Cookies, Cache, Proxy-Einstellungen, etc.

Methoden und Events von Modulen​

Für Module, die keine Klassen sind, müssen deren Methoden und Events unter ## Methods und ## Events aufgelistet werden.

Verwende AutoUpdater als Beispiel:

# autoUpdater

## Events

### Event: 'error'

## Methoden

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

Klassen​

  • API-Klassen oder Klassen, die Teil von Modulen sind, müssen unter dem Kapitel ## Klassen: Klassenname aufgeführt werden.
  • Eine Seite kann mehrere Klassen haben.
  • Konstruktoren müssen mit Überschriften der Ebene ### aufgelistet werden.
  • Statische Methoden müssen unter dem Kapitel ### Static Methods aufgelistet werden.
  • Instanz-Methoden müssen unter einem ### Instanz-Methoden Kapitel aufgelistet werden.
  • Alle Methoden, die einen Rückgabewert haben, müssen ihre Beschreibung mit "Returns [TYPE] - [Return description]" beginnen
    • Wenn die Methode ein Object zurückgibt, kann dessen Struktur angegeben werden mit einem Doppelpunkt gefolgt von einem Zeilenumbruch, dann einer ungeordneten Liste der Eigenschaften im gleichen Stil wie die Funktionsparameter.
  • Instanzereignisse müssen in einem ### Instance Events-Kapitel aufgelistet werden.
  • Instanzereignisse müssen in einem ### Instance Properties-Kapitel aufgelistet werden.
    • Instanz-Eigenschaften müssen mit "A [Property Type] ..." beginnen

Die Session und Cookies-Klassen als Beispiel verwenden:

# Sitzung

## Methoden

### session.fromPartition(Partition)

## Statische Eigenschaften

### Sitzung. efaultSession

## Klasse: Sitzung

### Instanz Ereignisse

#### Event: 'will-download'

### Instanz Methoden

#### `ses. etCacheSize()`

### Instanz Eigenschaften

#### `ses.cookies`

## Klasse: Cookies

### Instanz Methoden

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

Methoden und ihre Argumente​

Das Kapitel der Methoden muss in folgender Form sein:

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

* `required` string - Eine Parameterbeschreibung.
* `optional` Integer (optional) - Eine weitere Parameterbeschreibung.

...

Überschrifthöhe​

Die Überschrift kann ### oder #### sein, je nachdem, ob die Methode zu einem Modul oder einer Klasse gehört.

Funktionssignatur​

Bei Modulen ist objectName der Name des Moduls. Bei Klassen muss es der Name der Instanz der Klasse sein und nicht der Modulname.

Beispielsweise müssen die Methoden der Session-Klasse unter dem session-Modul ses als objectName verwenden.

Optionale Argumente werden von eckigen Klammern [] mit dem optionalen Argument sowie dem erforderlichen Komma angemerkt, wenn dieses optionale Argument einem anderen Argument folgt:

erforderlich[, optional]

Argumentbeschreibungen​

Detailliertere Informationen zu jedem der Argumente werden in einer ungeordneten Liste unterhalb der Methode vermerkt. 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.

Wenn das Argument vom Typ Array ist, verwende die Kurzform [] mit dem Typ des Wertes innerhalb des Arrays (zum Beispiel any[] oder string[]).

Wenn das Argument vom Typ Promise ist, parametriere den Typ mit dem, was der Promise zurückgibt (zum Beispiel Promise<void> oder Promise<string>).

Wenn ein Argument mehrere Typen aufweisen kann, trenne diese durch |.

Die Beschreibung der Typargumente von Function sollte deutlich machen, wie sie aufgerufen werden kann und die Typen der Parameter auflisten, die an die Funktion übergeben werden.

Plattformspezifische Funktionalität​

Wenn ein Argument oder eine Methode nur für bestimmte Plattformen gilt, werden diese Plattformen eine durch Leerzeichen getrennte, kursiv gedruckte Liste nach dem Datentyp angegeben. Werte können macOS, Windows oder Linux sein.

* `animate` boolean (optional) _macOS_ _Windows_ - Animiere das Objekt.

Ereignisse​

Das Ereignis-Kapitel muss in folgender Form sein:

### Event: 'wake-up'

Gibt zurück:

* `time` string

...

Die Überschrift kann ### oder #### groß sein, je nachdem, ob das Ereignis zu einem Modul oder einer Klasse gehört.

Die Argumente eines Ereignisses folgen den gleichen Regeln wie Methoden.

Eigenschaften​

Das Eigenschaften-Kapitel muss in folgender Form sein:

### session.defaultSession

...

Die Überschrift kann ### oder #### groß sein, je nachdem, ob die Eigenschaft zu einem Modul oder einer Klasse gehört.

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    |  <!--
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))
  })

Übersetzungen der Dokumentation​

Siehe Elektron/i18n