From MapbenderWiki

Contents 1 PHPdoc-Style 1.1 What is PHPdoc? 1.2 What are the rules? 1.3 Common PHPdoc tags (doc-tags) 1.4 Example

PHPdoc-Style

The PHP code within mapbender should be documented using the PHPdoc-Style. A full reference and good documentation can be found on the website of PHPdoc.

What is PHPdoc?

PHPdoc is a set of simple rules advising coders to comment their code in a defined way. It is rather widely in use in many PHP based projects.

Using PHPdoc, the code will be easy readable and highly comparable. Additionally the source can easily be parsed later to extract technical documentation of the source.

What are the rules?

Use doc-blocks to comment on the code. A docblock is a comment that looks like this:

 /**
  * This is a doc-block
  */

Notice the structure of the doc-block: it is mainly a "normal" /* */ comment with two exceptions:

1. the starting /*-part has an extra asterisk (*),
2. every new line within the doc-block has to start with the asterisk.

It is common to indent every line within a doc-block so that al starting asterisks form a vertical rule:

/**
 * This is a doc-block
 * 
 * having lines indented, makes
 * doc-blocks easy recognisable.
 */

In general this block precedes the code it documents.

The fist line in a doc-block is the short description, whereas all other lines either belong to the long description or have a special meaning (see section Common PHPdoc tags (doc-tags)).

One simple doc block with a short and along description might look like this:

/**
 * Appends the string ' World!' to the argument.
 *
 * This function takes one argument of type STRING. 
 * It will append the string ' World!' to that argument
 * and return the result immediatly.
 */
function sendGreetingsToTheWorld ($prefix = 'Hello') {
  return $prefix . ' World!';
}

Common PHPdoc tags (doc-tags)

Within the doc-block you can simply describe the following code (and you should do so) as we just did above. But you can also use special doc-tags, these will give you structured information on common topics concerning the code.

A doc-tag starts with the AT-sign (@) followed by a signal word, e.g.

/**
 * @author <john.patrick.doe@example.com> John Doe
 */

This tag declares John Doe as the author of the following lines. It gives contact details (john.patrick.doe@example.com) and helps to find contributers one might ask if something does not work as expected.

There are many doc-tags, the following list gives some examples (We might expand the list by ourselves):

• @abstract
• @access (public|private)
• @author Name [<email>] [, ...]
• @const[ant] label [description]
• @copyright description
• @deprec[ated] label
• @final
• @global (object objecttype|type) [$varname] [description]
• @link URL description
• @module label
• @modulegroup label
• @package label
• @param[eter] (object objecttype|type) [$varname] [description]
• @return (object objecttype|type) [$varname]
• @see (function()|$varname|((module|class)::)(function()|$varname)) [, ...]
• @since label
• @static
• @throws exception [, exception]
• @todo
• @var[iable] (object objecttype|type) [$varname] [description]
• @version label

Example

/**
 * Appends the string ' World!' to the argument.
 *
 * This function takes one argument of type STRING. 
 * It will append the string ' World!' to that argument
 * and return the result immediatly.
 * 
 * @param string the prefix to use for the greeting.
 * @return string the full greeting string.
 * @author <john.patrick.doe@example.com> John Doe.
 * @todo expand so other thing may be greeted as well.
 */
function sendGreetingsToTheWorld ($prefix = 'Hello') {
  return $prefix . ' World!';
}