Yii 1.1: How to generate Yii-like Documentation

44 followers

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.

Specification

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):

img1

Now lets take it by parts

Class documentation:

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

Will generate: Class Documentation

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: Property Doc

And:

Property Extended Doc

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: Method Documentation

And:

Extended Method Documentation

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:

Links

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:

Custom Link Text

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

Total 9 comments

#15427 report it
Kellerkind at 2013/11/08 10:13am
Private methods and properties

I like that extentsion. Can somebody tell me how to comment private methods and properties? It is a must have for internal documentation. phpDocumentor had a flag for this. Other doc-generators have it too (doxygen,...).

#14435 report it
Hudson Nguyen at 2013/08/11 12:52pm
Exceed 1GB of memory and broken

It works pretty good except a few things: 1. The generated doc should have a left panel for TOC 2. Biggest issue is the code was build to generate doc for the framework which is pretty small. My project is 1Gb (in total, not code only but it's still a lot of classes) and while i am excluding all the vendors it exceeds 1Gb memory limit for PHP. 3. DefaultController.php is widely used in each module and if your project (like mine) has 2+ DefaultController, this tool doesn't work.

The Git repo seems to be death, i am not sure if I should folk it and fix issue #1 and #2. Issue #3 I don't think it can be fixed if the project doesn't utilize namespace.

#13715 report it
demo.ideaentity at 2013/06/19 08:31am
Only framework and some views are documented

I expected all my components and other files would be documented but to my suprise only framework related classes are documented and some views from my project.

I went to my project protected folder and then tried this command .\yiic docs 'C:\Docs\ProjDocs\Documentation'

#9878 report it
Asgaroth at 2012/09/18 05:44pm
@tom@ku

Check Documenting Modules, it might be something similar.

#9872 report it
tom@cu at 2012/09/18 12:07pm
Getting an error on Compile..

Im getting the error:

PHP Error[2]: include(Yiiauth.php): failed to open stream: No such file or directory
    in file /var/yii/framework/YiiBase.php at line 423
#0 /var/yii/framework/YiiBase.php(423): autoload()
#1 unknown(0): autoload()
#2 /var/www/stoneOps_yii_Ver1/protected/components/Controller.php(8): spl_autoload_call()
#3 /var/www/stoneOps_yii_Ver1/protected/commands/docs/DocsModel.php(32): require_once()
#4 /var/www/stoneOps_yii_Ver1/protected/commands/docs/DocsModel.php(20): DocsModel->findClasses()
#5 /var/www/stoneOps_yii_Ver1/protected/commands/DocsCommand.php(307): DocsModel->build()
#6 /var/www/stoneOps_yii_Ver1/protected/commands/DocsCommand.php(152): DocsCommand->buildModel()
#7 /var/yii/framework/console/CConsoleCommandRunner.php(68): DocsCommand->run()
#8 /var/yii/framework/console/CConsoleApplication.php(92): CConsoleCommandRunner->run()
#9 /var/yii/framework/base/CApplication.php(162): CConsoleApplication->processRequest()
#10 /var/yii/framework/yiic.php(34): CConsoleApplication->run()
#11 /var/www/stoneOps_yii_Ver1/protected/yiic.php(7): require_once()
#12 /var/www/stoneOps_yii_Ver1/protected/yiic(4): require_once()

when i run the documentation build command... Any ideas???

#8545 report it
Asgaroth at 2012/06/11 12:39pm
@ale.nakamura

Instrucctions have not changed, I can't help you if you don't tell me what the problem.

#8544 report it
ale.nakamura at 2012/06/11 10:55am
Active?

This project still active? The project on GitHub the las modification is from 1 year ago.

And i follow the instructions of instalation, but the yiic don't with the command docs. How to enable this?

Thanks. It's a great project.

#8266 report it
Marc Busque at 2012/05/22 05:56am
Yii Documentor

I modified Yii doc builder and developed Yii Documentor. It can be used to generate Yii style documentation not only for applications but as well for extensions or the framework itself. For applications or extensions it can add also the framework API or add links to its external API, and links to source code in external repository can be added, too. Hope it's useful!

#3762 report it
锐 子 at 2011/05/05 07:12pm
Good job

Good job

Leave a comment

Please to leave your comment.

Write new article
  • Written by: Asgaroth
  • Updated by: fsb
  • Category: How-tos
  • Yii Version: 1.1
  • Votes: +45
  • Viewed: 25,560 times
  • Created on: May 5, 2011
  • Last updated: Nov 29, 2012
  • Tags: doc