Development standards: PHPDoc

Introduction

The main purpose of this document is to provide a more formal definition of the PHPDoc standards to use when developing within SGI V10 core or SGI V10 modules. Much of what is presented here can be consulted on the PSR-5: PHPDoc and phpDocumentor websites.

Definitions

• "PHPDoc" is a section of documentation which provides information on aspects of a "Structural Element".

• "Structural Element" is a collection of Programming Constructs which MAY be preceded by a DocBlock. The collection contains the following constructs:

  • require(_once)
  • include(_once)
  • class
  • interface
  • trait
  • function (including methods)
  • property
  • constant
  • variables, both local and global scope

  It is RECOMMENDED to precede a "Structural Element" with a DocBlock where it is defined and not with each usage. It is common practice to have the DocBlock precede a Structural Element but it MAY also be separated by an undetermined number of empty lines.

  /** @var int $int This is a counter. */
  $int = 0;
  
  // there should be no docblock here
  $int++;

  or

  /**
  * This class acts as an example on where to position a DocBlock.
  */
  class Foo
  {
    /** @var string|null $title contains a title for the Foo */
    protected $title = null;
  
    /**
     * Sets a single-line title.
     *
     * @param string $title A text for the title.
     *
     * @return void
     */
    public function setTitle($title)
    {
        // there should be no docblock here
        $this->title = $title;
    }
  }

• "DocComment" is a special type of comment which MUST:

  • start with the character sequence /** followed by a whitespace character
  • end with */ and
  • have zero or more lines in between

  In the case where a DocComment spans multiple lines, every line MUST start with an asterisk (*) that SHOULD be aligned with the first asterisk of the opening clause.

  Single line example:

  /** <...> */

  Multiline example:

  /**
  * <...>
  */