Clone wiki

Rarangi / docsyntax

How to write documentation

To generate the documentation, Rarangi read the "doc comments" which are in your source code. A "doc comment" is a comment which follow this syntax:

<?php
/**
 * here a doc comment
 */

Note the /** which is indicate that the comment is a doc comment, not a classical comment. You should use this kind of comments before each function, class, interface, global variable etc. You must also use a doc comment at the begining of each php file.

In a doc comment, you can write a short description, but also a long description. You can add some "tags" to specify some properties of the component you document. Here is a typical exemple:

<?php
/**
 * the short description
 *
 * the long description Lorem ipsum dolor sit amet, consectetur adipiscing elit.
 * Pellentesque at nisl vel libero lacinia malesuada. In consectetur velit feugiat
 * diam cursus in iaculis felis malesuada. In libero erat, rhoncus quis malesuada et,
 * accumsan nec sapien. Donec nec neque et lacus lobortis pellentesque.
 *
 * @param string $name the name of the user
 * @return boolean  true if it's ok
 */
function login($name) {
   // the code....
}

The short description is all lines, from the first line to the first empty line. Text which is after the first empty line is the long description. Descriptions are optional, although it is recommended to write them. After descriptions, you can indicate some tags. A tag is a name which begin by a "@", and a tag is followed by other parameters, depending of the tag itself. In the example, you have a first tag, @param, which indicates that the "$name" parameter of the function is a string, and should contain the name of a user. Then the tag @return indicates that the function returns a boolean.

Updated