API Style Guide
Dieses Topic beschreibt den Aufbau der Topics PythonApi und JythonApi und wie die einzelnen Topics auszusehen haben
Einstieg
Die Einstiegsseite ist in Customizing und Server aufgeteilt.
- Module, die dokumentiert werden, kommen in die entsprechende Tabelle
- Packages bekommen eine extra Überschrift mit eigener Tabelle
Formatierung
Generell gilt:
- Python Objekte müssen entweder auf die Doku der Klasse/Funktion verlinken, oder in
Monospaceformatiert sein- Dies gilt auch für Konstante wie
TrueoderFalse
- Dies gilt auch für Konstante wie
Modultopics
Ein Modultopic ist immer wie folgt aufgebaut:
- Klassen
- Statische Variabeln
- Methoden
- Klassenmethoden
- Statische Methoden
- Properties
- Funktionen
Klassen
In diesem Bereich werden die Klassen des Moduls aufgeführt.
- An oberster Stelle kann, wenn hilfreich, ein Klassendiagramm stehen
- Zu jeder Klasse kann optional ein kurzer Text stehen, wofür die Klasse gut ist
Statische Variabeln
Statische Variabeln werden tabular wie folgt beschrieben:
| Variable | Description |
|---|---|
| NameOfTheClass.NAME_OF_THE_PARAMETER | Ein kurzer Text, der die Variable beschreibt |
Methoden / Klassenmethoden / Statische Methoden
Methoden werden tabular wie folgt beschrieben:
| Function | Parameters | Return Value | Description |
|---|---|---|---|
NameOfTheClass.name_of_the_function(self, a_mandatory_parameter, a_keyword_argument='Default Value') | mandatory_parameter: Here we describe the parameter a_keyword_argument: Here we describe the parameter | What this method returns | A description of the method. |
Zu beachten ist folgendes:
- Keyword arguments sind kursiv und werden mit ihrer default value beschrieben.
- In der Parameterbeschreibung ist eine Zeile Abstand zwischen den Argumenten und Keyword arguments.
- Wenn ein Argument auf ein Dataitem in PLANTA zurückzuführen ist, z.B. die Projekt-ID, so kann das Argument einfach mit einem Verweis auf das entsprechende DI dokumentiert werden. In diesem Fall Projekt-ID.
- Primärschlüssel sind über Fremdschlüssel zu bevorzugen. Als Beispiel kann man sich eine
TaskKlasse vorstellen, die einen 463er beschreibt und mit Projekt und Vorgangs ID initialisiert wird. In diesem Fall ist für die Projekt-ID ein Verweis auf DI001001 über DI001097 zu bevorzugen
- Primärschlüssel sind über Fremdschlüssel zu bevorzugen. Als Beispiel kann man sich eine
- Ist der erwartete Wert in einem Enum/einer Konstante zu finden, sollte die entsprechende Stelle verlinkt werden.
- Die Argumentbeschreibung soll nur den Datentyp/Art von Wert beschreiben, den die Funktion erwartet. Komplexere Argumente sollten in der Beschreibung erklärt werden.
Properties
Properties werden tabular wie folgt beschrieben:
| Property | Getter | Setter | Description |
|---|---|---|---|
| NameOfTheClass.name_of_the_property | Ein kurzer Text, der das Property beschreibt |
Auch hier gilt:
- Ist ein Property direkt mit einem Dataitem in PLANTA verknüpft, so verlinkt man einfach das entsprechende Dataitem.