Zum Hauptteil springen

Electron Documentation Style Guide

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

Überschriften​

  • Each page must have a single #-level title at the top.
  • Chapters in the same page must have ##-level headings.
  • Sub-chapters need to increase the number of # in the heading according to their nesting depth.
  • The page's title must follow APA title case.
  • All chapters must follow APA sentence case.

Using Quick Start as example:

# Schnellstart

...

## Hauptprozess

...

## Rendering-Prozess

...

## Starten Sie Ihre App

...

### Als Distribution ausführen

...

### Manuell heruntergeladene Binärdateien von Electron

...

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

Markdown-Dateien​

This repository uses the markdownlint package to enforce consistent Markdown styling. For the exact rules, see the .markdownlint.json file in the root folder.

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

  • Use sh instead of cmd in code blocks (due to the syntax highlighter).
  • Keep line lengths between 80 and 100 characters if possible for readability purposes.
  • Keine Verschachtelung listet mehr als 2 Ebenen auf (aufgrund des Markdown-Renderers).
  • All js and javascript code blocks are linted with standard-markdown.
  • 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​

Each module's API doc must use the actual object name returned by require('electron') as its title (such as BrowserWindow, autoUpdater, and session).

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

Using the session module as an example:

# session

> Manage browser sessions, cookies, cache, proxy settings, etc.

Methoden und Events von Modulen​

For modules that are not classes, their methods and events must be listed under the ## Methods and ## Events chapters.

Using autoUpdater as an example:

# autoUpdater

## Events

### Event: 'error'

## Methoden

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

Klassen​

  • API classes or classes that are part of modules must be listed under a ## Class: TheClassName chapter.
  • Eine Seite kann mehrere Klassen haben.
  • Constructors must be listed with ###-level headings.
  • Static Methods must be listed under a ### Static Methods chapter.
  • Instance Methods must be listed under an ### Instance Methods chapter.
  • All methods that have a return value must start their description with "Returns [TYPE] - [Return description]"
    • If the method returns an Object, its structure can be specified using a colon followed by a newline then an unordered list of properties in the same style as function parameters.
  • Instance Events must be listed under an ### Instance Events chapter.
  • Instance Properties must be listed under an ### Instance Properties chapter.
    • Instanz-Eigenschaften müssen mit "A [Property Type] ..." beginnen

Using the Session and Cookies classes as an example:

# 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 - A parameter description.
* `optional` Integer (optional) - Another parameter description.

...

Überschrifthöhe​

The heading can be ### or ####-levels depending on whether the method belongs to a module or a class.

Funktionssignatur​

For modules, the objectName is the module's name. Bei Klassen muss es der Name der Instanz der Klasse sein und nicht der Modulname.

For example, the methods of the Session class under the session module must use ses as the objectName.

Optional arguments are notated by square brackets [] surrounding the optional argument as well as the comma required if this optional argument follows another argument:

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.

If the argument is of type Array, use [] shorthand with the type of value inside the array (for example,any[] or string[]).

If the argument is of type Promise, parametrize the type with what the promise resolves to (for example, Promise<void> or Promise<string>).

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

The description for Function type arguments should make it clear how it may be called and list the types of the parameters that will be passed to it.

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. Values can be macOS, Windows or Linux.

* `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

...

The heading can be ### or ####-levels depending on whether the event belongs to a module or a class.

Die Argumente eines Ereignisses folgen den gleichen Regeln wie Methoden.

Eigenschaften​

Das Eigenschaften-Kapitel muss in folgender Form sein:

### session.defaultSession

...

The heading can be ### or ####-levels depending on whether the property belongs to a module or a class.

API History​

Ein "API History"-Baustein ist ein YAML-Code-Baustein mit einem HTML-Kommentar, der direkt hinter dem Markdown-Header für eine Klasse oder Methode platziert werden soll. Zum Beispiel 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.

Zweck des API History Blocks ist es, zu beschreiben, wann/wann/wie/warum eine API war:

  • Hinzugefügt
  • Geändert (in der Regel gravierende Änderungen)
  • Veraltet

Jede im Block aufgelistete API-Änderung sollte einen Link zur PR enthalten, wo diese Änderung zusammen mit einer optionalen Kurzbeschreibung der Änderung vorgenommen wurde. 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.

Es gibt ein paar Style-Richtlinien, die nicht durch das linting Skript abgedeckt sind:

Format​

Immer an dieses Format festhalten:

API HEADER | #### win.flashFrame(flag) BLANK LINE | HTML COMMENT OPENING TAG | BLANK LINE |

YAML​

  • Verwenden Sie zwei Leerzeichen für Einrückungen.
  • Keine Kommentare verwenden.

Beschreibung​

  • Beschreibungen immer mit doppelten Anführungszeichen (z.B. "Beispiel").
  • Describe the change in a way relevant to app developers and make it capitalized, punctuated, and past tense.
    • Refer to Clerk for examples.
  • Beschreibungen kurz halten.
    • Ideally, a description will match its corresponding header in the breaking changes document.
    • Bevorzugen Sie, wann immer möglich, die Versionshinweise der zugehörigen PR.
    • Developers can always view the breaking changes document or linked pull request for more details.

Platzierung​

Generell sollten Sie den API-History-Block direkt hinter dem Markdown Header für eine veränderte Klasse oder Methode platzieren. Es gibt jedoch einige Fälle, in denen dieses zweideutig ist:

Chromium bump​

Manchmal bezieht sich eine gravierende Änderung nicht auf eine der bestehenden APIs. In diesem ist es in Ordnung, den API-Verlauf nirgends hinzuzufügen.

Änderung, die mehrere APIs betrifft​

Manchmal sind mehrere APIs bei einer gravierenden Änderung erforderlich. In diesem Fall platzieren Sie den API-History-Block unter dem top-level Markdown-Header für jede der beteiligten 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)

Beachten Sie, dass kein API-History-Block hinzugefügt wurde:

  • contextBridge.exposeInMainWorld(apiKey, api)

Da diese Funktion nicht geändert wurde, nur wie sie verwendet werden können:

  contextBridge.exposeInMainWorld('app', {
-   ipcRenderer,
+   onEvent: (cb) => ipcRenderer.on('foo', (e, ...args) => cb(args))
  })

Übersetzungen der Dokumentation​

See electron/i18n