Documenting your PHP code with ApiGen

IF THERE IS TIME! Usually there is no time for documentation, but if there is time for documentation let's make one!

Lets do this with APIGen, because at this time it supports php 7.

composer require apigen/apigen --dev

How does it look in the code:

/**

* The Model class is a sample class that holds all queries

Just explaining what does class do.

* @package Main

This is group of packages

* @example <br />

* //from controller index.php

* $model->getDiseases($request->getAttribute('offset'), $request->getAttribute('limit'))<br />

The main problem with many documentation is: No examples. I love this part, because it shows how to use the code and what is the result

* @version 0.01

* @author Davor Radic <[email protected]>

*/

There are many options like @version, @autor etc.

lets go to the method of the class getDiseases()

/**

 \* Get all diseases from database

 \* @example <br/>

 \* //from controller index.php &lt;br /&gt;

 \*  $model-&gt;getDiseases\($request-&gt;getAttribute\('offset'\), $request-&gt;getAttribute\('limit'\)\)&lt;br /&gt;

 \*  //gets results as: &lt;br /&gt;

 \*  array\("meta" =&gt; array\('total-results' =&gt; int\),&lt;br /&gt;

 \*        "data" =&gt; array\('diseases' =&gt; array\("id" =&gt; int, &lt;br /&gt;

 \*                                            "name" =&gt; "name of disease"\)....&lt;br /&gt;

 \*  \)

 \* 

 \* @param int $offset Offset

 \* @param int $limit Limit

 \*/

function getDiseases\($offset, $limit\) {

    $offset = \(isset\($offset\) && $offset > 0\) ? intval\($offset\) : 1;

    $limit = isset\($limit\) ? intval\($limit\) : 10;

First it describes what method does. Then it gives example how to use it and the parameters that are passed to method.

Conclusion:
Always give description of class, method, variable and example how it is used. On this way it is very likely that other programmers will understand your code.