Documentation is definitively one of the most important aspects of an app, since it provides information about its flows and structures. Unfortunately, it is often omitted due to lack of time.
Yii give us a powerful tool to automatically generate a pretty documentation. Basically, it uses all the documentation comments present in the app, those starting with /** instead of the classic /*.
Therefore, we have the advantage that comments in the code are used to produce a complete documentation.
Inside these comments, there are few keywords that are usable according to the context—file, class, or function/method.
In case of a file, the most common keywords to put on top are:
@link url, whereurlis the reference URL linked to the file@copyright text, where text is the content of copyright@license url, whereurlis the reference to license content
In case of a class, the most common keywords to put on top are:
@author name, where name is the name of the author@since version, where version is the version of the project in which this class has been included
In case of a function/method, the most common keywords to put on top are:
@param type name, where type is the type of parameter and name is the name of the parameter passed as an argument of the function@return type, where type is the returned type@throws class, where class is the exception class thrown by the exception
Besides API documentation, Yii provides tools to create pretty guide files that are in the .md format (typical of GitHub). It is easy to find information on formatting a .md file by surfing the Internet.
Let's now see which commands automatically produce a documentation from the Yii app.
There are two kinds of documentation:
- API documentation, which is a reference of each
.phpfile in the project, completed with doc comments referred to a single file, class, or function - Guide, which is a pretty manual for the app, created using the
.mdfiles that Yii renders in pretty.htmlfiles
The first step is to install api-doc, if it is not already present.
Point to the project root folder and launch this command:
$ php composer.phar require --prefer-dist yiisoft/yii2-apidoc
This will install the yii2-apidoc extension.
Now we can launch the command to produce an API documentation starting from the project root folder:
$ vendor/bin/apidoc api ./ ../app-doc
The parameters are as follows:
- The first parameter,
api, identifies the command to execute - The second parameter,
./, identifies the path of the source files to scan - The third parameter,
../app-doc, identifies the destination folder of the created documentation
After launching the command, going to the ../app-doc folder on a browser will show us the API documentation created by the framework.
When we make any changes in the source file, it is necessary to relaunch the command to update the API documentation. The second kind of documentation is the guide, a set of .html files produced by .md files.
So we need to create a folder, starting from the project root folder, for example, the folder named guide, where we will put all the .md files that we want to convert into .html pretty files from the command guide.
Now we are ready to launch the command to create our guide, which is totally similar to the previously made API command:
$ vendor/bin/apidoc guide ./guide ../app-doc
This command will convert all the .md files present in the ./guide folder into .html files, storing them in the ../app-doc folder (together with the API documentation files).
Let's make a concrete example. Starting with the basic template project, create a new controller named TestDocController in TestDocController.php at basic/controllers:
<?php
/**
* This file contains a controller to demonstrate api documentation tool.
*
* @link http://www.example.com/
* @copyright Copyright (c) 2015
* @license http://www.example.com/license/
*/
namespace appcontrollers;
use Yii;
use yiiwebController;
/**
* This is a controller class to demonstrate api documentation tool.
*
* @author Fabrizio Caldarelli
* @since 1.0
*/
class TestDocController extends Controller
{
/**
* Make sum of the operands
*
* @param float $a first operand
* @param float $b second operand
* @return float sum of parameters
* @author
*/
public function makeSum(float $a, float $b)
{
return $a+$b;
}
}Now open a shell console on host, and from the project root folder, launch the command to generate the API documentation:
$ vendor/bin/apidoc api ./ ../app-doc
This will create the documentation for all files starting with the root folder (./) and storing the HTML result files in ../app-doc.
Now, on your browser, go to http://hostname/app-doc and we will display the API documentation index page. Search for TestDocController.php in the side menu and click on it. This should be the output:
TestDocController API documentation
Now, we want to demonstrate the second kind of documentation—guide documentation.
Create a folder from the project root folder named app-guide. In it, put a new file named test-doc-controller.md with the following content:
## TestDoc Controller This is the guide for TestDoc Controller. ## Functionalities It is provided makeSum function, that makes a sum of two values passed as parameter ``` $a = 10; $b = 20; $c = $this->makeSum(float $a, float $b) // $c = 30; ```
Go to the shell console of the hosting and from the project root folder, launch the command to generate the guide documentation:
$ vendor/bin/apidoc guide ./app-guide ../app-doc
This will create the guide documentation for all .md files in the ./app-guide folder and will store .html results in ../app-doc.
On your browser go to http://hostname/app-doc/guide-test-doc-controller.html, you should see the following screen:
TestDocController guide documentation