API Style Guide

This topic describes the structure of the PythonApi and JythonApi topics and what the individual topics should look like

Access

The start page is divided into Customizing and Server.

The general rule is:

Python objects must either have a link to the documentation of the class/function or be formatted in Monospace
- This also applies to constants like True or False

A module topic is always structured as follows:

In this area, the module classes are listed.

At the top position there can be a class diagram, if considered helpful
For each class there can be a short text describing what the use of the class is

Static variables are described in table form as follows:

Variable	Description
NameOfTheClass.NAME_OF_THE_PARAMETER	A short text which describes the variable

Methods are described in table form as follows:

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.

Note the following:

Keyword arguments are in italics and are filled with their default value.
In the parameter descriptions there is a one-line gap between arguments and keyword.
If an argument can be ascribed to a data item in PLANTA, e.g. the project ID, then the argument can simply be documented with a reference to the respective DI. In this case the project ID.
- Primary keys are to be favored over foreign keys As an example one could think of a Task class which describes a 463 data table and is initialized with project and task ID. In this case, a reference to DI001001 via DI001097 is to be favored for the project - ID.
If the expected value can be found in a enum/constant, the respective position should be linked.
The argument description is only to describe the data/value type which the function expects. Complex arguments are to be explained in the description.

Properties are described in table form as follows:

property	getter	setter	Description
NameOfTheClass.name_of_the_property			A short text which describes the property

Here too:

If a property is directly linked to a data item in PLANTA, the respective data item is simply linked.