Introduction ¶

Something a good application cant miss is documentation, and what would be better than some nice formatted HTML documentation that can be auto-generated from your code, we know several tools that already do this like phpDocumentor, but today we are introducing Yii Docs Generator which is a modification of the code that Yii itself uses to generate its documentation, thank phpnode for this wonderful work.

To generate nice HTML however we must follow some specifications that this wiki will try to describe.

The following are 2 classes that we will be using as an example:

<?php

/**
 * short class description.
 * Extended class description
 * 
 * @author me
 * @version 0.1
 * @package application.components
 */
class DummyClassA extends CController
{
	/**
	 * short method description
	 * 
	 * extended method description
	 * 
	 * @param string $bar param description {@link DummyClassB}
	 * @return DummyClassA 
	 */
	public function foo($bar)
	{
	}
}

And

<?php
/**
 * short class description.
 * Extended class description
 * 
 * @author me
 * @version 0.1
 * @package application.components
 */
class DummyClassB extends CWidget
{
	/**
	 * @var DummyClassA short description.
	 * extended property description
	 */
	public $parent;
	
	/**
	 * short method description
	 * 
	 * extended method description
	 * 
	 * @param DummyClassA $parent param description
	 * @param string $bar param description
	 * @return DummyClassB
	 */
	public function foo(DummyClassA $parent, $bar)
	{
	}
}

This classes would generate a documentation like the following (Docs Index):

Now lets take it by parts

Class documentation: ¶

/**
 * short class description.
 * Extended class description
 * 
 * @author me
 * @version 0.1
 * @package application.components
 */

Will generate:

Only the first line is show in the index, this first line then, should be a short description about the class. in the following lines you can describe in more detail what the class does and perhaps show some sample code. take CGridView as an example:

/**
 * CGridView displays a list of data items in terms of a table.
 *
 * Each row of the table represents the data of a single data item, and a column usually represents
 * an attribute of the item (some columns may ... etc

Here is the index example and the full description

Tip: Anywhere in the extended descriptions, of class or method, you can use <pre></pre> to paste some sample code that will keep formatted in the generated HTML.

All other @tags are optional, but you would like to have at least the @package tag as this will group your classes in the index doc. all other tags are recognized and added in the detailed view of the class (ie. @author, @version, @since, etc)

Attribute Documentation ¶

/**
  * @var DummyClassA short description.
  * extended property description
  */
  public $parent;

Will Generate:

And:

Again we have short and extended description, but this time we have a type hint, this is important as if the type is not a native type (string, array, etc) but instead is a class that is also being documented, then Yii Docs Generator will notice and create a link to that class for us, as you can see in the images, it created a link to our DummyClassA.

Again the short description is the first line, but this time remember to put a period (.) after the short description to help Yii Docs Generator indentify it easier.

Method Documentation ¶

<?php
	/**
	 * short method description
	 * 
	 * extended method description
	 * 
	 * @param DummyClassA $parent param description
	 * @param string $bar param description
	 * @return DummyClassB
	 */
	public function foo(DummyClassA $parent, $bar)
	{
	}

Will Generate:

And:

Yes...short and extended description, you already know how they work so lets take a look at @param.

The correct syntax would be @param {type} ${param_name} {description} As in property documentation if the type is a defined class Yii Docs Generator will create links for us.

Whenever you need to create a link to a Class, a Class property or a class method you can use the following syntax anywhere in your docs:

/**
	 * short method description
	 * 
	 * For Classes:
	 * {@link CController}.
	 * Class property
	 * {@link CController::id}.
	 * Class Method
	 * {@link CController::render}.
	 * 

Will generate links this way:

If you want to show a custom string for the link, you can place a space ( ) and the string you want to show as link. for example:

* 
	 * 
	 * Custom link text
	 * 
	 * {@link CController::render check the render method!}
	 * 

Will generate:

Documenting Modules ¶

The Yii Docs Generator cant check classes imported using [CModule::setImport] so we have to add [Yii::import] for every one of this aliases at the beginning of the module class or the generator will break. you can always remove this imports after you have generated the documentation.

So, if you have a setImport like this:

<?php
		$this->setImport(array(
			'mymodule.components.*',
			'mymodule.models.*',

		));

You will have to add this at the beginning of your "MymoduleModule" class

<?php
Yii::import('application.modules.mymodule.components.*');
Yii::import('application.modules.mymodule.models.*');

Note that you have to use the full alias path 'application.modules.mymodule' and not only 'mymodule', thats becuase Yii Docs Generator does not instantiate any class so the path aliases for modules are never set.

Documenting Views ¶

If you want to document your views, add a doc block right at the top of the view file with the file description. You can also specify the parameters that your view file receives by using the @uses tag, e.g.

<?php
/**
  * Some text describing what the view does goes here
  * @uses CActiveDataProvider $dataProvider The data provider for this model
  * @uses User $model The user model
  */

If you don't want to document your views you can turn this behaviour off by adding the parameter noviews to the end of the shell command, e.g.

./yiic docs /path/to/your/docs/folder noviews

Thats it for now, the Yii Docs Generator is still a work in progress but as you can see its already a powerful too, that will get you some nice documentation and as you can see its pretty easy to use.

The Yii Docs Generator also comes with a check command, that will help you check if there is some important missing documentation, but wont check things like @package of class documentation so its always good to check your files manually after using this command.

Resources: ¶

• [Yii Docs Generator on Git]( https://github.com/phpnode/Yii-Docs-Generator "Yii Docs Generator")
• Yii Docs Generator on Yii