Skip to content

PHP Code Documentation

The API documentation of Contrexx is automatically generated based on its PHP source code using the documentation tool phpDocumentor 2. To ensure that the generation of the documentation works flawlessly, the whole source of Contrexx has to be documented properly. This is done using so-called DocBlocks.

Refer to the documentation of phpDocumentor 2 on how to properly document the PHP source code.

See also Wikipedia article about PHPDoc.

Guidelines

  1. First, Study the introduction What is a DocBlock?
  2. Then use at least the mandatory Tags as listed below to properly document the code
  3. Add useful (see Best practices for writing code comments) inline code documentation

Example

Example file-level-, exception- & class-DocBlock for a class of component Config:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
<?php
declare(strict_types=1);

/**
 * Cloudrexx
 *
 * @link      https://www.cloudrexx.com
 * @copyright Cloudrexx AG
 *
 * This file is part of Cloudrexx.
 *
 * Cloudrexx is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Affero General Public License as
 * published by the Free Software Foundation, version 3 of the License.
 *
 * Cloudrexx is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU Affero General Public License for more details.
 *
 * "Cloudrexx" is a registered trademark of Cloudrexx AG.
 * The licensing of the program under the AGPLv3 does not imply a
 * trademark license. Therefore any rights, title and interest in
 * our trademarks remain entirely with us.
 */

namespace Cx\Core\Config\Model\Entity;

/**
 * @copyright   Cloudrexx AG
 * @author      John Doe <john.doe@example.org>
 * @package     cloudrexx
 * @subpackage  core_config
 */
class ExampleException extends \Exception {}

/**
 * @copyright   Cloudrexx AG
 * @author      John Doe <john.doe@example.org>
 * @package     cloudrexx
 * @subpackage  core_config
 */
class Example {}

Mandatory tags

File-level / namespace / class / interface / trait

property / constant

require(_once) / include(_once)

Note

Add comment about the specific reason why a require(_once) / include(_once) has been used*

function (including methods)

all other tags are nice to have and should be set where useful (for example author of a function if not the same as the author of the class)

Inheritance

phpDocumentor does automatically inherit all documentation of parent elements (see Inheritance at phpDocumentor). So in theory no additional documentation is required on inherited elements (classes, interfaces, methodes, etc.). However to indicate a local element as documented we shall do so by adding a DocBlock as follows:

1
2
3
/**
 * @inheritDoc
 */

However, if the local element has been modified and must therefore be documented, we do only have to document the changed parts of it (@param, @global, @return and @throws) and if required the description itself. For the description, the special inline tag {@inheritDoc} can be used to import the description of the parents DocBlock. Example:

1
2
3
4
5
6
7
8
/**
 * This is the summary of the redefined method.
 *
 * Now follows the description of the overloaded element:
 * {@inheritDoc}
 *
 * @param string This argument has been added to the redefined method
 */

Not used tags