Articles Code Documentation
Code Documentation
How To Document Your PHP Classes - Page 4
by: Stefano Locati
|
August 25, 2000
Documenting Functions or Methods
Member functions or methods are documented with the
@function tag.
/*! @function getItemingroup
@abstract gets a bagitem of a given group and a given position
@param groupno int - the delivery group ordinal position in the bag
@param pos int - the position of the bagitem within the group
@result Object - the BagItem in a given position of given group
or -1 if it could not be found
*/
Documentation of a method.
A
@function tag declares a function and is followed by a function or a member
function name. Then you can use @abstract and @discussion
tags like before. There are however two additional tags. The @param tag is used to
describe function's parameters; the first word is assumed to be the variable name, while the rest is a free text
description. I suggest to state the expected type of the variable, even if PHP is not a strong typed language.
The @result tag is used to describe the return value.Documenting Variables
Variables or class variables are described with the
@var tag. Within this tag,
the first word is assumed to be the variable's name, while the rest is free text description. Like before
I suggest that writing the expected type of the variable is good. It's also a good idea to document all
your class variables.
Documentation of a class variable.
/*! @var idsession string - an unique session identifier */ var $idsession;
A Final Touch
/*! @header myprojectname
@abstract a virtual store to shop on mars
@discussion The difference [...]
*/
The
@header tag is used to provide some general info about the project or the
group of classes being documented. The @header tag itself is followed by the project name and
is useful to complement it with @abstract and @discussion
tags. Since classes are generally in different files (and it is usually a good idea to have one file per class named
after the class name), you might wonder where you should place the @header tag. The answer is,
surprisingly enough, anywhere. I suggest to place it in a separate file if it's a long discussion or on the
top of the most important class if it's a shorter comment.
