Found at: http://publish.ez.no/article/articleprint/29/

PHP class documentation

Publishing date: 15.11.2000 15:47

In this article I will explain a method of documenting your PHP classes. This article is based on the eZ phpdoc generator.

A screenshot of the HTML class reference.

This article will show you a simple method of documenting your PHP classes. If you use the syntax I've described in this article, you can have nice looking reference documentation automatically generated for you. Go to phpdoc.ez.no to download the eZ phpdoc program. eZ phpdoc generates nice looking HTML class reference, a Lyx document and man pages for the classes. To see an example of generated documentation you can go to doc.ez.no.

A quick example

The code below gives you an example of how you can use the syntax of eZ phpdoc to document your classes. You have to put every class in a separate file, for eZ phpdoc to parse them correctly.

//!! Module Name
//! A brief description of the class
/*!
  This is a more complete description of the class.
*/

class MyClass
{
  /*!
    This is the contructor of MyClass. It handles....
  */
  function MyClass()
  {
  }

  /// This is a variable description.
  var MyVar;
}

More details

Every class should be grouped in to a module. This makes it easier to find related classes. The brief description of a class should only give a one sentence description of what the class does. The detailed class description is where you should describe how the class works and what you can do with it. You should only document what the class does, not how. The user of a class will be satisfied to know how to use it.

The detailed description field can contain example code and links to related classes. The code snippet below shows how you can use these features.

//!! Module Name
//! Short description.
/*!
  This is the detailed description..

  Here are some example code:
  \code
  $myObj = new MyClass();
  \endcode
  \sa MyOtherClass
*/

You can write code example between the \code and the \endcode tag. The \sa tag will make a link to other classes, and a "see also" field will appear in the class documentation.

Function description

Every function should have a small description. The description should be short and contain a description of the arguments. The return values should also be described. The code snippet below shows an example of a function description.

/*!
  This is a description of the function. The argument $value can be
  of the type MyObjet.
*/
function aSmallFunction( $value )
{

}

Variable description

Even variables should be described. Personally I don't describe every variable in the class. I only explain special variables or variables which are specially important. The code snippet below shows an example of a variable description.

/// This variable does something special. Note: foo bar.
var $myVar;

TODO

One nice feature with eZ phpdoc is the ability to store a todo list internally in the class documentation. All the todo items will be generated in an overview page where each todo item is linked to the class it belongs to. If you have an empty line you get a new todo item.

/*!TODO
  First thing to do.

  Second thing to do.

  Yet, another thing to do. This one spans over two lines
  and contains more information about what to do.
*/

C++ wannabe

Since PHP does not have the ability to set member functions to private or static, we have implemented the feature to set this as a special comment tag.

The example below shows how you can use the \static tag to define a
function as static in your documentation.

/*!
 \static
 This function is static. 
*/
function aStaticFunction()
{
}

Let's get some privacy

If you have functions in your class which does not belong in the public scope, i.e. another class should not call that function, you should make that function private. This does certainly not make the function private, but it gets marked in the documentation as private. It is up to other developers not to call that function from another class.

/*!
 \private
 This function is private.
*/
function aPrivateFunction()
{
}

eZ phpdoc usage

The eZ phpdoc program is a Perl command line script. You can get the latest version of it here.

If you run the command ezphpdoc.pl without any arguments you get a message like the one shown below.

eZ phpdoc v0.9
    Usage: phpdoc.pl sourcedir... -o outputdir
           --disable_todo ( will remove the todo listing )
    Notice: phpdoc will search the sourcedir recursively and use all 
    .php files containing a class definition.

To generate documentation from the classes in the directories classpath1, classpath2 and /home/myuser/classpath3 run the following command. By default the output is generated in a ./doc/ catalogue.

#ezphpdoc.pl classpath1/ classpath2/ /home/myuser/classpath3 -o /home/myuser/documentation

If you want to disable the TODO listing, e.g. you will show the documentation but hide the todo's, add the argument --disable_todo.

| Back to normal page view |