#native_company# #native_desc#

How To Document Your PHP Classes Page 4

By Stefano Locati
on 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
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

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.