API Style Guide
This topic describes the structure of the PythonApi and JythonApi topics and what the individual topics are supposed to look like.
Access
The start page is divided into Customizing and Server.
- Modules that are documented go in the respective table
- Packages receive an extra heading with their own table
Format
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
TrueorFalse
- This also applies to constants like
Module Topics
A module topic is always structured as follows:
- classes
- static variables
- methods
- class methods
- static methods
- properties
- functions
classes
In this area, the classes of the module 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
In table form, static variables are described as follows:
| Variable | Description |
|---|---|
| NameOfTheClass.NAME_OF_THE_PARAMETER | A short text which describes the variable |
Methods / Class Methods / Static Methods
In table form, methods are described 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. |
The following must be observed:
- 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
Taskclass 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.
- Primary keys are to be favored over foreign keys As an example one could think of a
- 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
In table form, properties are described as follows:
| property | getter | setter | Description |
|---|---|---|---|
| NameOfTheClass.name_of_the_property | A short text which describes the property |
Here, the same rule applies:
- If a property is directly linked to a data item in PLANTA, the respective data item is simply linked.