PHPBuilder - How To Document Your PHP Classes Page 4



RSS Twitter
Articles 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
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.

« Previous Page
1
|
2
|
3
|
4
|
5
Next Page »

Comment and Contribute

Your comment has been submitted and is pending approval.

Author:
Stefano Locati

Comment:



Comment:

(Maximum characters: 1200). You have characters left.