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 voncmd
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
- undjavascript
-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.
- Wenn die Methode ein
- 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