docs/php_code-style_documentation.md

   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 !!! 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."
  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 interfere 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 properly 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.
  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).