/*! @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 */
@functiontag declares a function and is followed by a function or a member function name. Then you can use
@discussiontags like before. There are however two additional tags. The
@paramtag 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
@resulttag is used to describe the return value.
@vartag. 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.
/*! @var idsession string - an unique session identifier */ var $idsession;
/*! @header myprojectname @abstract a virtual store to shop on mars @discussion The difference [...] */
@headertag is used to provide some general info about the project or the group of classes being documented. The
@headertag itself is followed by the project name and is useful to complement it with
@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
@headertag. 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.