PHP Code Documentation

Introduction

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:

<?php
declare(strict_types=1);

/**
 * Cloudrexx
 *
 * @link      https://www.cloudrexx.com
 * @copyright Cloudrexx AG
 *
 * According to our dual licensing model, this program can be used either
 * under the terms of the GNU Affero General Public License, version 3,
 * or under a proprietary license.
 *
 * The texts of the GNU Affero General Public License with an additional
 * permission and of our proprietary license can be found at and
 * in the LICENSE file you have received along with this program.
 *
 * This program 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

• @copyright
• @author
• @package
• @subpackage

property / constant

• @var

require(_once) / include(_once)

• @ignore (as all classes should get loaded by the ClassLoader anyway)

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

function (including methods)

• @param (if any)
• @global (if any)
• @return (if not void)
• @throws (if so)

Recommended / useful tags

• @todo
• @deprecated
• @see
• @uses
• @since If the structural element is public, then use this tag to document the cloudrexx release since this feature became available
• @inheritDoc See section #Inheritance below

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:

/**
 * @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:

/**
 * 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

• @version