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 verbatim formatiert sein
  • Dies gilt auch für Konstante wie True oder False

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 Task Klasse 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 DI 001001 über 001097 zu bevorzugen
• 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