All code must be documented with inline comments. The syntax is that known from the Java programming language (JavaDoc). This way code documentation can automatically be generated using tools like phpDocumentor or Doxygen. The "official" tool used is phpDocumentor, so syntax and documentation usage are chosen to work best with it.
A file can contain different documentation blocks, relating to the file itself, the class in the file and finally the members of the class. A documentation block is always used for the entity it precedes.
The first documentation block in the file is essential for defining the package the file and it's contents belong to. Although it would not be strictly needed to have the file level documentation block (because each file contains only one class in FLOW3), we still use it because it
avoids warnings when rendering the documentation
makes sure that even code outside of classes is assigned to the correct package and documented correctly
That means that each file must contain a documentation block like shown below, right below the header stating the license:
Example 5.20. Standard file level documentation block
/**
* @package [packagename]
* @subpackage [subpackage name if necessary]
* @version $Id$
*/
The package tag is mandatory, the subpackage tag is optional and should only be used if needed.
Classes have their own documentation block describing the classes purpose, assigning a package and subpackage. Very often the code within a class is expanded and modified by a number of authors. We therefore recommend to add the names of the developers to the method documentation. An exception should be the documentation for interfaces where you list all authors in the interface documentation. Exceptions itself never have an author annotation.
Example 5.22. Standard class documentation block
/**
* First sentence is short description. Then you can write more, just as you like
*
* Here may follow some detailed description about what the class is for.
*
* Paragraphs are seperated by a empty line.
*
* @package [packagename]
* @subpackage [subpackage name if necessary]
* @version $Id$
* @license http://opensource.org/licenses/gpl-license.php GNU Public License, version 2
*/
class F3_FLOW3_SomeClass {
...
Example 5.23. Standard interface documentation block
/**
* First sentence is short description. Then you can write more, just as you like
*
* Here may follow some detailed description about what the interface is for.
*
* Paragraphs are seperated by a empty line.
*
* @package FLOW3
* @subpackage MVC
* @version $Id$
* @license http://opensource.org/licenses/gpl-license.php GNU Public License, version 2
* @author Robert Lemke <robert@typo3.org>
* @author Karsten Dambekalns <karsten@typo3.org>
*/
interface F3_FLOW3_SomeInterface {
...
Example 5.24. Standard exception documentation block
/**
* First sentence is short description. Then you can write more, just as you like
*
* Here may follow some detailed description about what the interface is for.
*
* Paragraphs are seperated by a empty line.
*
* @package FLOW3
* @subpackage MVC
* @version $Id$
* @license http://opensource.org/licenses/gpl-license.php GNU Public License, version 2
*/
class F3_FLOW3_SomeException {
...
Additional tags or annotations, such as @see or @aspect, can be added as needed.
Properties of a class should be documented as well. We use the short version for documenting them:
Example 5.25. Standard variable documentation block
/**
* A short description, very much recommended
* @var string
*/
protected $title = 'Untitled';
For a method, at least all parameters and the return value must be documented. Please also add your name by using the @author tag. The @access tag must not be used as it makes no sense (we're using PHP >= 5 for some reason, don't we?)
Example 5.26. Standard method documentation block
/**
* A description for this method
*
* Paragraphs are seperated by a empty line.
*
* @param F3_Log_LoggerInterface $logger A logger
* @param string $someString This parameter should contain some string
* @return void
* @author Robert Lemke <robert@typo3.org>
*/
public function __construct(F3_Log_LoggerInterface $logger, $someString) {
...
A special note about the @param tags: The parameter type and name are seperated by one space, not aligned. Do not put a colon after the parameter name. Always document the return type, even if it is void - that way it is clearly visible it hasn't just been forgotten.
There are quite a few documentation tags that can be used. Here is a list of tags that can and should be used within the TYPO3 project:
@author
@copyright
@deprecated
@example
@filesource
@global
@ignore
@internal
@license
@link
@package
@param
@return
@see
@since
@subpackage
@todo
@uses
@var
@version
Some are useless for PHP5 and PHP6, such as the tag for declaring a variable or method private:
@access
![[Important]](images/admonitions/important.png) | Important |
|---|---|
If you are unsure about the meaning or ose of those tags, look them up in the phpDocumentor manual, rather than doing guesswork. |
![[Note]](images/admonitions/note.png) | Note |
|---|---|
There are more tags which are used in FLOW3, however their purpose is not documention but configuration. Currently annotations are also used for defining aspects and advices for the AOP framework. |