Commit | Line | Data |
---|---|---|
07242e17 MS |
1 | --- |
2 | title: Documentation | |
3 | sidebar: sidebar | |
4 | permalink: php_code-style_documentation.html | |
5 | folder: php | |
6 | parent: php_code-style | |
7 | --- | |
8 | ||
9 | {% include callout.html content="The following documentation conventions are used by us for our own packages. While you do not have to follow every rule, you are encouraged to do so." type="info" %} | |
10 | ||
11 | ||
12 | ## Database Objects | |
13 | ||
14 | ### Database Table Columns as Properties | |
15 | ||
16 | As the database table columns are not explicit properties of the classes extending `wcf\data\DatabaseObject` but rather stored in `DatabaseObject::$data` and accessible via `DatabaseObject::__get($name)`, the IDE we use, PhpStorm, is neither able to autocomplete such property access nor to interfer the type of the property. | |
17 | ||
18 | To solve this problem, `@property-read` tags must be added to the class documentation which registers the database table columns as public read-only properties: | |
19 | ||
20 | ``` | |
21 | * @property-read propertyType $propertyName property description | |
22 | ``` | |
23 | ||
24 | The properties have to be in the same order as the order in the database table. | |
25 | ||
26 | The following table provides templates for common description texts so that similar database table columns have similar description texts. | |
27 | ||
28 | | property | description template and example | | |
29 | |----------|----------------------------------| | |
30 | | unique object id | `unique id of the {object name}`<br>**example:** `unique id of the acl option`| | |
31 | | id of the delivering package | `id of the package which delivers the {object name}`<br>**example:** `id of the package which delivers the acl option`| | |
32 | | show order for nested structure | `position of the {object name} in relation to its siblings`<br>**example:** `position of the ACP menu item in relation to its siblings`| | |
33 | | show order within different object | `position of the {object name} in relation to the other {object name}s in the {parent object name}`<br>**example:** `position of the label in relation to the other labels in the label group`| | |
34 | | required permissions | `comma separated list of user group permissions of which the active user needs to have at least one to see (access, …) the {object name}`<br>**example:**`comma separated list of user group permissions of which the active user needs to have at least one to see the ACP menu item`| | |
35 | | required options | `comma separated list of options of which at least one needs to be enabled for the {object name} to be shown (accessible, …)`<br>**example:**`comma separated list of options of which at least one needs to be enabled for the ACP menu item to be shown`| | |
36 | | id of the user who has created the object | ``id of the user who created (wrote, …) the {object name} (or `null` if the user does not exist anymore (or if the {object name} has been created by a guest))``<br>**example:**``id of the user who wrote the comment or `null` if the user does not exist anymore or if the comment has been written by a guest``| | |
37 | | name of the user who has created the object | ``name of the user (or guest) who created (wrote, …) the {object name}``<br>**example:**``name of the user or guest who wrote the comment``| | |
38 | | additional data | `array with additional data of the {object name}`<br>**example:**`array with additional data of the user activity event`| | |
39 | | time-related columns | `timestamp at which the {object name} has been created (written, …)`<br>**example:**`timestamp at which the comment has been written`| | |
40 | | boolean options | ``is `1` (or `0`) if the {object name} … (and thus …), otherwise `0` (or `1`)``<br>**example:**``is `1` if the ad is disabled and thus not shown, otherwise `0` ``| | |
41 | | `$cumulativeLikes` | ``cumulative result of likes (counting `+1`) and dislikes (counting `-1`) for the {object name}``<br>**example:**``cumulative result of likes (counting `+1`) and dislikes (counting `-1`) for the article``| | |
42 | | `$comments` | `number of comments on the {object name}`<br>**example:**`number of comments on the article`| | |
43 | | `$views` | `number of times the {object name} has been viewed`<br>**example:**`number of times the article has been viewed`| | |
44 | | text field with potential language item name as value | `{text type} of the {object name} or name of language item which contains the {text type}`<br>**example:**`description of the cronjob or name of language item which contains the description`| | |
45 | | `$objectTypeID` | ``id of the `{object type definition name}` object type``<br>**example:**``id of the `com.woltlab.wcf.modifiableContent` object type``| | |
46 | ||
47 | ||
48 | ## Database Object Editors | |
49 | ||
50 | ### Class Tags | |
51 | ||
52 | Any database object editor class comment must have to following tags to properly support autocompletion by IDEs: | |
53 | ||
54 | ```php | |
55 | /** | |
56 | * … | |
57 | * @method static {DBO class name} create(array $parameters = []) | |
58 | * @method {DBO class name} getDecoratedObject() | |
59 | * @mixin {DBO class name} | |
60 | */ | |
61 | ``` | |
62 | ||
63 | The only exception to this rule is if the class overwrites the `create()` method which itself has to be propertly documentation then. | |
64 | ||
65 | The first and second line makes sure that when calling the `create()` or `getDecoratedObject()` method, the return value is correctly recognized and not just a general `DatabaseObject` instance. | |
66 | The third line tells the IDE (if `@mixin` is supported) that the database object editor decorates the database object and therefore offers autocompletion for properties and methods from the database object class itself. |