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. Die Art des Arguments wird entweder durch JavaScript primitiven (z.B. string, Promise oder Object), eine benutzerdefinierte API-Struktur wie Electron's Cookie oder der Platzhalter any festgelegt.

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.

Übersetzungen der Dokumentation

Siehe Elektron/i18n