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 | ||
9003992d | 9 | !!! info "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." |
07242e17 MS |
10 | |
11 | ||
12 | ## Database Objects | |
13 | ||
14 | ### Database Table Columns as Properties | |
15 | ||
0b828ab7 | 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 interfere the type of the property. |
07242e17 MS |
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 | ||
0b828ab7 | 63 | The only exception to this rule is if the class overwrites the `create()` method which itself has to be properly documentation then. |
07242e17 MS |
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. | |
5f9eb7a9 MS |
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. |
67 | ||
68 | ||
69 | ## Runtime Caches | |
70 | ||
71 | ### Class Tags | |
72 | ||
73 | Any class implementing the [IRuntimeCache](https://github.com/WoltLab/WCF/blob/master/wcfsetup/install/files/lib/system/cache/runtime/IRuntimeCache.class.php) interface must have the following class tags: | |
74 | ||
75 | ```php | |
76 | /** | |
77 | * … | |
78 | * @method {DBO class name}[] getCachedObjects() | |
79 | * @method {DBO class name} getObject($objectID) | |
80 | * @method {DBO class name}[] getObjects(array $objectIDs) | |
81 | */ | |
82 | ``` | |
83 | ||
84 | These tags ensure that when calling any of the mentioned methods, the return value refers to the concrete database object and not just generically to [DatabaseObject](https://github.com/WoltLab/WCF/blob/master/wcfsetup/install/files/lib/data/DatabaseObject.class.php). |