How to document your PHP class (ii)
[BR]
Author: Stefano Locati translation: Limodou
Document a function or method
A member function or method is documented using 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 is found
*/
--------------------------------------------------------------------------------
Documentation of a method.
The @function tag declares a function and follows the name of the function or member function. Then you can use @abstract and @discussion tags as before. However, there are two additional tags. @param tags are used to describe the parameters of a function; the first word is assumed to be the name of the variable, and the other is any text description. I recommend declaring the type of variable you want, although PHP is not a strongly typed language. @result tag is used to describe the return value.
Document variables
Variables or class variables are described by using the @var tag. In this tag, the first word is considered to be the name of the variable, while others are arbitrary text descriptions. As before, I recommend that it is good practice to write out the desired variable type. It's also a good idea to document all class variables.
Document a class variable.
--------------------------------------------------------------------------------
/*! @var Idsession String-an Unique session identifier * *
var $idsession;
--------------------------------------------------------------------------------
Final Contact
--------------------------------------------------------------------------------
/*! @header MyProjectName
@abstract a virtual store to shop on Mars
@discussion the difference [...]
*/
--------------------------------------------------------------------------------
@header tags are used to provide general information about the document or class group that is being documented. The @header tag itself follows the name of the project and can be supplemented with @abstract tags and @discussion tags. Because classes usually exist in different files (a file with a class and the name of a class is a good idea), you might want to know where to put the @header tag. The answer is amazing. My advice: If it's longer, put it in a separate file, or, if it's a short description, put it in front of the most important class.
How to modify scripts for PHP
The initial Headerdoc script from Apple is for C or C + + header files, so you need to make some minor changes to it in PHP. If you are not interested in the details, you can download it from here and skip the section below.
The only thing you can do to modify the source program is to make the script acceptable in the main Perl file. php and. PhP3 suffixes.
--------------------------------------------------------------------------------
$ diff headerdoc2html.pl/usr/local/bin/headerdoc2html
195c195
< ($rootFileName = $filename) =~ s/. (h|i) $//;
---
> ($rootFileName = $filename) =~ s/. (H|I|PHP|PHP3) $//;
--------------------------------------------------------------------------------
Run the script
After installing the script, suppose your class is placed in the classes subdirectory, and you want to put the generated document in the Docs directory, you should execute this command:
Headerdoc2html-o Docs classes/*.php
Unfortunately, if there are multiple PHP files, the script has a bad habit of splitting those files into different directories, making it difficult to navigate through the document of the class. And because the original script was written for the C + + header file (the header file has only the declarations of classes and functions without their definition), the script prints all the code in the function name until it encounters ";", so typically the first line of code.
But before you finally feel hopeless, relax, because I wrote a simple script to solve both of these problems.
--------------------------------------------------------------------------------
Cat classes/*.php | Sed ' s/*{/;#{/g ' | tr ' # "
"> docs/all.php
Headerdoc2html-o Docs docs/all.php
RM docs/all.php
--------------------------------------------------------------------------------
If you want to know why I'm here using the TR command instead of using SED, the reason is that the SED 3.02 version still used on Redhat 6.2 does not handle line breaks. Should replace the new version of SED 3.02a. If you are interested in sed, you can see the SED FAQ.
Good luck with your document work!
Translation something:
Because this article is used in a Linux environment, there may be a problem with Windows. I'll try, I can think of something, I can't think of any way out.
Original Author: Limodou
Source: phpx
