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 name. Then you can use
tags like before. There are however two additional tags. The
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
@function tag declares a function and is followed by a function or a memberfunction name. Then you can use
@abstract and @discussiontags like before. There are however two additional tags. The
@param tag is used todescribe 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
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.
@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
group of classes being documented. The
is useful to complement it with
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
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.
@header tag is used to provide some general info about the project or thegroup of classes being documented. The
@header tag itself is followed by the project name andis useful to complement it with
@abstract and @discussiontags. 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.
