content:
What is phpdocphpdoc structure and function phpdoc base phpdoc keywords and document flags Generate document Advanced: Customized Document Reference About the author's evaluation of this article
related information:
1. Use PEAR to write your next PHP program 2, common module
subscription:
DeveloperWorks Newsletter
Pan Fan Engineer, Beijing Saidi Data Co., Ltd. May 2001
For a developer, the document is always one of the most headaches. Moreover, it is likely that you will take a different attitude towards documents:
When you use someone else's code library, most want to get its technical documentation, especially when it is very tight, and you have to hit the scalp to read those emotional code.
When you write your own procedure, the least want to do things is to write a special technical documentation, you will free yourself with how much reason: my code is already clear enough, don't have to reply to it again. ...
Perhaps to alleviate this contradiction, there are many tools to help you, automatically generate the appropriate API documentation by extracting the corresponding annotations from the source code. POD2MAN in JavaDoc, Perl in Java. In contrast, PHP seems to lack the corresponding tools, but as PHPDOC is constantly improving, this situation has been greatly changed.
There is one in the coding rule of the first PEAR, and the comments in the Pear program should be able to be converted by PHPDoc. It can be seen that PHPDOC is in a PEAR. Today, we will discuss phpdoc, this excellent Pear program.
What is phpdocphpdoc is a very good module under the PEAR. Its goal is to implement the functions similar to Javadoc, which can quickly generate an API document with mutual reference, indexing, and other functions. If you have used the document generated by Javadoc (such as JDK documents), you will be very clear if you haven't used it, then the following is a screenshot of a phpdoc generated its own document page:
From the figure, you can know that the document generated by phpdoc is very similar. It has a variety of index: PackageIndex: This is the module to index ClassTree: This is the inheritance of your PHP class, you can generate a tree Index ModuleGroups: This is divided by module ElementList: This is your alphabetical index of all your elements (methods, procedures / functions, variables).
The structure and function of PHPDoc Since phpdoc itself is also a PEAR app, we first understand its structure. PHPDOC is written in all the idea of OOP, which is also recommended by PEAR, PHPDOC's working principle:
PHPDoc scan the PHP source code below to specify the directory, scan the keywords, intercept the desired annotation, then analyze the dedicated TAG in the annotation, generate the XML file, then establish the corresponding corresponding class and module information Index, generate an XML file for the generated XML file, using custom template to output as an HTML file.
From the design, PHPDOC uses 2 superclars: phpdocobject and phpdocerror. This is the basic class of the entire phpdoc. This method is also recommended by PEAR, that is, when you write your own application framework, it is best to have a basic superclass, while other subclasses or functional classes. There is a common ancestor. During the scan source code, phpdoc uses the form similar to GREP. It is not as usually what we usually think. According to the author's explanation, he has tried to use regular expressions, but the resource occupation And the speed of processing is difficult to satisfactorily, so this unconventional form is used, and the specific implementation of interested readers can refer to source code. I think that PHPDOC is satisfactory is that the results are preserved in XML, which means that other applications can easily share this data, and PHPDCO also provides the corresponding interface, you can implement this interface. To generate other forms, such as PDF, Latex, Word, and more. At present, PHPDOC's analysis results can be manifested in HTML, and there may be more forms in the future. Even in the form of HTML, since the template mechanism (he uses PEAR IT and ITX module to implement), you can easily make your own style, PHPDoc base phpdoc is generated from your source code Documentation, therefore the process of noticing your program, that is, the process of your documentation.
From this point, PHPDOC prompts you to develop good program habits, try to use specifications, clear text to make a comment for your procedure, and more less to avoid post-employment of documents and documents. Problem.
It is very important to comply with PHPDoc specification, mastering this, basically you can use phpdoc to work for you.
Note Divided into document comments and non-document comments in PHPDOC
3.1 Document Note Document Note is actually some special forms of multi-line comments, usually put on specific keywords you need to comment (these keywords refer to those keywords that will be analyzed by phpdoc, please See the description of the following paragraph 4). Below is an example of a document comment:
/ **
* Common base class of all phpdoc classes (briefly, in the index list)
*
* AS A Kind of Common Base Class PHPDocObject Holds
* Configuration Values (E.G. Error Handling) and debugging
* Methods (E.G. Introspection ()). It Does Not Have a Construction,
* So you can always inheritig phpdoc classes from this
* Class without Any Trouble. (Detailed Features Description)
*
* @Author ulf wendel
* @version $ ID: phpdocobject.php, v 1.3 2001/02/18 15:29:29 UW EXP $
* @package phpdoc (document tag)
* /
Class phpdocObject {
.....
}
The above document comments will generate the following documentation:
phpdocobject
PHPDocObject
CommON Base Class of All PHPDoc Classes Private Class PHPDocObject
Common base class of all phpdoc classes
As a Kind of Common Base Class PHPDocobject Holdsconfiguration Values (E.G. Error
Handling) and debuggingmethods (E.g. Introspection ()). It Does Not Have A
Constructor, So you can always inheritig phpdoc class from thisclass without any trouble.
Authors ulf wendel
Version $ ID: phpdocObject.php, v 1.3 2001/02/18 15:29:29 UW EXP $
3.2 Non-document Note If your comment is not placed in front of the keyword specified by phpdoc, then phpdoc thinks that the comments you do are non-document comments, will not be analyzed by phpdoc, and will not appear in you. API text.
3.3 How to write your documentation Note From 3.1 We can see, a documentary annotation is composed of 3 parts, namely: Function and Description Area, Detailed Description Area, Document Tag District.
First, the first line is a note "/ **" started, then the carriage return, starting from the 2nd line is the functional profile area, the function is the "*" started by indentation, in Jane The body and this "*" number are separated by spaces (note that in the document, it is started with *, and these * remain aligned into the indentation format). The text of the function is generally a concise indication of the functionality of this class, method, or function, and the function of the function is shown in the index area in the generated document.
The functional profile is an empty annotation line, which is used to divide the exact area and the detailed description area. The functional detailed description area is also guided by indent '* ", this part is mainly for your API's functionality, use, if possible, can also use the method. In this section, you should focus on you The usual use of API functions or methods, uses, and indicates whether it is a cross-platform (if involved), for information related to the platform, you want to treat with those general information, usually the same line, Then write the precautions on a particular platform or special information, which should be sufficient so that your readers can write corresponding test information, such as boundary conditions, parameter range, breakpoint, and more.
Behind the Detailed Description Area, is a blank annotation line, then the document tag area, you can write related document tags (these document tags, please refer to Section 4 below), indicate some technical details information The most important thing is to call the parameter type, the return value is extremely type, inheritance relationship, related methods / functions, etc. Multiple document markers should use the same indentation, form a "markup block" for easy reading and analysis.
One line under the document tag area is the end of the end line "* /". Note that at the end tag * / should be followed by a carriage return, do not add other things, otherwise it may cause PHPDoc analysis error.
The above is the basic method of writing a documentary annotation. Here we discuss specifications and techniques when writing documents. 3.4 Document Write Guide When you describe your code or function, it is best to follow most of the habits, it is popular, "You tell me what I want to know". " To this end, here will introduce some of the skills and specifications of writing document comments, hoping to help you:
Use to log keywords and name and related code. If you need to reference some keywords, variable names in the document, or you have to give some code, then you'd better use these keywords, variable names, codes, and you Document is separated, so that when readers read, they will know that these will be running code, keywords rather than your descriptive language. Use simple, clear languages to avoid lengthy, complex, and long sentences to describe. In particular, in the index portion of the function, the parameter description, etc., try to use the simple understanding of the language to reveal the main information, and put other details in the detailed description. If you use English, it is recommended to use a phrase and not necessarily. If English is used, it is recommended to use the three-person order form to explain the method, the function description, you need to explain this method "What", not "how to do". Therefore, it is recommended that your explanation is to start with verbs, such as "return record number", "delete a given record", etc. When you are built from a certain object or variable from the current class, use "this" instead of "the" to refer to the object or variable avoid empty talk, nonsense, for what you want to give, in you Behind the API has its functional description, it is it able to "self-developed". The so-called empty talk, nonsense refers to your description is not a functional description, but just a simple repetition and row of the API name, or use another API to explain this API, come to the end, your readers don't know the content you want to express. . Your description should be those who have not been added from your class name, method name, or a function name, instead of repeating your API name. Many people may have made this mistake in a lot of people (including me), and below is an example:
/ **
* Set up user record set
*
* @Param text given the table name
* /
Function set_user_record ($ TABLE) {
What can you know from above this comment? Therefore, this annotation is actually nonsense, because you can see from the function name, below is improved:
/ **
* Open the system user table and set to the current user record set, this recordset will be used for the default record set for subsequent related user data update operations. If it fails, a database error is thrown.
*
* @Param Text The table name of the system user table to open.
* /
Function set_user_record ($ TABLE) {
Use links properly. Adding an appropriate link for your documentation (including your other classes, PHP functions, etc.) Adding an appropriate link: You can use the @LINK tag to add to the link of the relevant API, but you There is no need to add a connection to all the APIs referenced in the document, which will be very beautiful, here there is a simple standard: If the user sees an API in this place, I really want to go to click to get more information, so Helps them understand your document, and even if the link is added, only when it first appears, there is no need to add the same LINK. Due to the functional limit of phpdoc, a PHP file only defines a class or module, do not put the definition of the class and module in the same file, otherwise phpdoc may not work, at least the current version is this. If your framework is built using OOP, avoid using module or module groups simultaneously; at the same time, you should carefully plan your application structure, your application frame should be a structure similar to tree, don't be too much, for example, you can Two supercles are designed, named as superclars for normal applications and error, and are derived from these 2 classes. PHPDoc keyword and document sign
4.1 Keywords Class, Function, Var, Include (include_once, required, require_once), Define
The comments made in front of these keywords are considered to be documentary comments.
4.2 Document Tag Description: Use range refers to the keyword that the tag can be used to modify, or other document tag @abstract use range: Class, Function, Var Description The current class is an abstract class.
Note: From the PHP language perspective, it is not like Java, C , supports this concept of abstract classes. There is no corresponding keyword to modify a certain class is an abstract class. Since PHPDOC actually borrowed Javadoc practices, many document markers are also followed by Javadoc, such as Abstract, Access, Final, etc. Although these features are not supported from the language level, it is still worth recommending from the user's perspective.
Example:
/ **
* This is an abstract class that paints five-star patterns.
* @ABSTRACT
* /
Class paint_start {
/ **
* Draw quantity
* @ABSTRACT
* /
Var $ Number;
/ **
* Draw a five-star pattern
* @ABSTRACT
* /
Function Paint () {
;
}
}
@access (public | private) Scope: Class, Function, Var, Define, Module
Indicates access to this variable, class, function / method. If your function is internally, you should indicate that it is private, this is the benefit, even if PHP can't prevent other people from using your private data, at least you communicate such information to your users, this is a private The function, there is therefore not guaranteed that in the future version is still present; for the user, it is expressed as @Private data and methods, you should not be used directly, even if you can do this.
Example:
/ **
* This is an abstract class that paints five-star patterns.
* @ABSTRACT
* @access public
* /
Class paint_start {
/ **
* Draw quantity
* @ABSTRACT
* @access private
* /
Var $ Number; / **
* Draw a five-star pattern
* @ABSTRACT
* @access public
* /
Function Paint () {
;
}
}
@Author Name [
Indicate the author information, in turn is the author's name, Email address, and other communication information. If there are multiple authors, use multiple @Author in turn:
* @Author night sailer
@Sister (Function () | $ VARIABLE) Scope: Class, Function, Var, Define, Module, USE
Point out the brothers, functions, or variables. These functions, classes, variables have similar information and and achieve the same functions. For example, the number and type of the parameters returned, the same function is the same. In this case, you can use @brother or @Sister to indicate its brother function, no information such as the function of repeating the writing function.
Example:
/ **
* This is an abstract class that paints five-star patterns.
* @ABSTRACT
* @access public
* /
Class paint_start {
/ **
* Draw quantity
* @ABSTRACT
* @access private
* /
Var $ Number;
/ **
* Draw a five-star pattern
* @ABSTRACT
* @access public
* /
Function Paint () {
;
}
/ **
* @brother point ()
* /
Function draw () {
;
}
}
@const [Ant] Label [Description] Use range: Define specifies that the constant is actually used to explain the constant defined by the define keyword definition of PHP.
@copyright Description Use: Class, Function, Var, Module, Define, USE indicates copyright information.
@Deprec [ATED] Label Use: Class, Function, Var, Module, Define, USE indicates not recommended or abandoned information.
If your function or method has been replaced by a new function method, or have been discarded, and readers have not been used to continue. Then you can use this sign to tell the reader, this function is just to keep compatibility, it is not recommended, if it has been replaced by other functions, it is also pointed out of this alternative.
example:
/ **
* Outdated class
*
* @Deprec 1.5-2000 / 12/06
* @access public
* /
Function dontusemeanymore () {
PRINT "don't use me any more. I have been deprecated."
}
@exclude label Usage: Class, Function, Var, Module, Define, USE indicates that the current annotation will not be analyzed, do not appear in the @Final Usage: Class, Function, Var indicates that this is a final class, Methods, attributes, it is forbidden to derive, modify. Example:
/ **
* PI
* @Final
* /
VAR $ PI = 3.1415926;
@Global (Object ObjectType | Type) [$ VARNAME] [Description] Usage: Function indicates a global variable referenced in this function:
/ **
* SIMULIERT INCLUDE_ONCE IN PHP 3.
*
* @global array $ __ @ used_files already included file list
* @access public
* /
Function Include_once ($ filename) {
GLOBAL $ __ used_files;
IF (! isset ($ __USED_FILES ["incrude_once"] [$ filename])) {
$ __ used_files ["incrude_once"] [$ filename] = TRUE
INCLUDE ($ filename);
}
}
@Include Description Using the range: Use of Use Indicates information about the included file. Example:
/ **
* Definition of abstract drawing class.
*
* @include function: _Require_
* /
Require ("Abstract.php");
@LINK URL Description Use: Class, Function, Var, Module, Define, USE Definition Online connection, as mentioned above, you can add an appropriate online link using @LINK. For example: @Link http://www.phpdoc.de/ phpdoc home
@Magic Description This tag is not explained in phpdoc, and the specific usage is still unclear.
@Module Label Usage: Module Defines the home module information, Label is the name of the module, and functions with the same module name will be combined in the index classification. If you don't use OOP's thoughts to write PEAR code, it is recommended that you use this tag to return the relevant function to the appropriate module so that your overall frame is not too zeroat and confusion.
@ModuleGroup Label Usage: Module Definition The Module Group Label is the name of this module group. If your application has a lot of modules, you can divide different modules according to logical functions, which is divided into corresponding module groups, which. Your application framework can have a relatively clear logical relationship. This is for the use of OOP programming. If you use OOP ideas, there is no need to use the concept of module groups, because directly use "Pack-Class-Base-Subclass" form to reflect your framework The structure is better than using the "Pack-Module Group - Module".
@Package Label Usage: Class, Module Defines the information of the home package, label is the name of this package. The name of the name of the same package will be partially together in the final document index. In fact, the package can still be understood as different namespace, although there is no name space concept, but you can belong to the same package, which is equivalent to organizing a name space, of course, you The application framework may have different packages, but unfortunately, in this case, you can't get the namespace from the grammar. You can only avoid different packages or class reintegments by artificial. @Param [Eter] (Object ObjectType | TYPE) [$ VARNAME] [Description] Use range: Function defines the parameter information of the function or method. This is the most commonly used document marks.
OjECTTYPE is the class name of the object, and Type points out the type of this parameter, which can be the following type:
String This parameter is a character type variable. Array This parameter is an array. Integer This parameter is a numeric. Integer (Octal) This parameter is a numeric shape and is stored in an octave. Integer (HexAdecimal) This parameter is a numeric shape and is stored in a hexadecimal mode. Boolean This parameter is a Boolean. Mixed This parameter is variable and can be combined above. However, in subsequent descriptions, the type of variable can be accepted.
$ VarName is the name of the ginseng
[Description] is an explanation for parameters.
If the function accepts multiple parameters, then follow the left to right, listed aligned with @param, as shown below:
*
* @Param Array $ tags array of tags returned by gettags
* @Param Array $ Data Array Where the allowed tags and their value is lopied to
* @Param Array $ ALLOWED ARRAY OF ALLOWED (Recognized) Tags
@return (Object ObjectType | TYPE) [$ VARNAME] Usage: Function Defines Function or Method's Return Information. The type of return information is the same as @Param, and $ VarName is the name of the returns variable, which can be available. Different are @return only one, there will be no multiple @return
@see (Function () | $ VARNAME | ((Module | Class) ::) (() | $ VARNAME)) [, ...] Usage: Class, Function, Var, Module, Define, USE Definition Reference functions, variables, and add corresponding super connections. This is also a more common marker. For related functions, variables, you can use @see to add a link to related functions and variables. Multiple related functions, variables are written in one line, and are separated by commas in the middle. The reference function, if the variable is the current class or module, then you can write functions directly, or the name of the variable, if it is a function to add parentheses (), the variable name is added to add $. It should be noted that the so-called variable name here should also be explained by @var, otherwise, phpdoc will not find the relevant reference to report. If you want to reference a function or variable of other classes or other modules, you can use the name of the class or module as a range indication in front of the function name, the variable name, and the intermediate :: Here are some examples: @see $ run_time, $ IDLE_TIME, $ Begin_Time, $ END_TIME @see getRuntime (), getIdletime (), getBegintime (), getEndtime () @see time: $ robun_time, time :: getBegintime ()
@since label Usage: Class, Function, Var, Module, Define, USE indicates which version starts from which version begins.
@Static use range: Class, Function, Var indicate variables, classes, and functions are static.
@THROWS Exception [, Exception] Use the range: Function points to the error exception that this function may thrown, and if you expect to have an exception in this function, then you can use the @Throws tag to explain these exceptions. What is it, in the case of an exception. For example, read disk file error, unable to connect to the database, network connection timeout or in some cases, you "deliberately" throw an exception.
@Todo Scope: Class, Function, Module, USE indicates a place that should be improved or not implemented
@var [Iable] (Object ObjectType | TYPE) [$ VARNAME] [Description] Use range: VAR Definition Description Variables / Properties. Object ObjectType | Type defines the type of your variable, the same name is the name of the variable as @param, you can use @see from other places to reference this name Description to variables
@version label Usage: Class, Function, Module, USE Definition Version information. You can of course hand writing these versions, but Pear recommends you to use CVS's $ ID tag to move your version information. The form is as follows:
@version $ ID This time when you checkout, CVS will automatically expand: @version $ ID: phpdocparsercore.php, v 1.4 2001/02/18 14:45:27 UW EXP
Generate documentation
5.1 Installing PHPDOC installation phpdoc is simple, actually because it has been released with PHP 4.05, so if your php is 4.05, then the phpdoc module will be found under the PEAR directory. If you don't find it, you can from phpdoc CVS Get a new source code. 5.2 Run PHPDoc Run PHPDOC to do some preparations, first adjust your php.ini parameters,
Because PHPDoc runs longer than the general PHP application, it is likely to exceed your maximum running time defined in php.ini (the default is 30 seconds), according to the author's recommendations: PIII, 60 seconds, 120 seconds PII, 240 seconds MMX200, 480 seconds if the configuration is lower. If you have timeout, you can extend these values properly.
Modify in php.ini:
;;;;;;;;;;;;;;;;;;;
Resource Limits;
;;;;;;;;;;;;;;;;;;;
MAX_EXECUTION_TIME = 480
Memory_limit = 8388608
If you don't want to modify the permissions of php.ini, then you can use the set_time_limit () function to set this time, how to use: set_time_limit (480); Setting from this point, running 480 seconds. Add this function in Index.php, you can reach the same effect with the modified php.ini.
Second, you have to modify the index.php file below the phpdoc directory:
// Directory with incrude files
Define ("phpdoc_include_dir", "c: / www / apache / doc /");
"C: / www / apache / doc / modified to your phpdoc" directory
// Important: set this to the linebreak sign of your system! Define ("linebreak", "/ r / n"); this is the sign of defining the wrap, the following is a wrap Enter, UNIX is just a carriage return. .
Below, do some custom work for your application to generate documents:
// sets the name of your application.
// the name of the application is used E.g. AS a page Title
$ DOC-> SetApplication ("phpdoc");
SetApplication () is used to set the name of your application and replace phpdoc to your application name.
// Directory WHERE YOURE Source Files Reside:
$ doc-> setsourceDirectory (phpdoc_include_dir);
SetSourceDirectory () Sets the directory where your application's PHP source file is located, replace phpdoc_include_dir to your actual directory.
// Save the generated docs here:
$ doc-> setTarget (phpdoc_include_dir. "apidoc /");
SetTarget () Sets the directory where your API document is stored, PHPDoc will generate XML and HTML files below this directory. Replace phpdoc_include_dir. "APIDOC /" with your own directory.
// Use these Templates:
$ doc-> setTemPlatedIRectory (phpdoc_include_dir. "render / html / templates /"); setTemplatedIRectory () Sets the directory of the template used by HTML. If you need to use a custom template, you can use this function to set the directory where your own template file is located.
// Source Files Have ONE Of these Suffixes:
$ doc-> setsourcefilesuffix (array ("php", "inc");
SetSourceFileSUFFIX () is used to set the extension of the PHP source file that you need to analyze. If you use other extensions, you need to add it here, for example, if you have previous PHP3 files, you need to add:
$ doc-> setsourcefilesuffix (array ("php", "incc", "php3"));
In this way, the basic customization work is complete, now you can run index.php in your browser, you have a welcome information, it starts to analyze the document. According to the status of the machine and the number of source code files, the document The time required for the analysis process will not be the same. After the analysis is over, the browser will display finish words, indicating that the analysis is complete, you can find the analysis results, including HTML and XML files below the directory you just specified.
5.3 Utilities Through phpdoc's index.php, although it can generate documentation, it is not that convenient, here I give a shell program Makeapidoco, you can use it to make it easy to generate your API document, no need to have every time To modify, do not have to start the browser.
The usage is as follows: makeapidoc -t your application title - Source program directory -D Generate Document Storage Directory
Before use, modify the following 2 lines: phpdoc_dir = "/ usr / local / lib / php / pear / phpdoc" # windows: c: / php / pear / phpdoc phpbin = "/ usr / local / bin / php" # Windows: c: /php/php.exe phpdoc_dir is a directory of phpdoc, phpbin is the path to the PHP executable.
This program actually uses PHP as a shellscript, but it is used in Bash. In fact, PHP can run as a normal shell script, just add -Q parameters, so do not print http header .
Advanced: Customized Output Document If you think the default phpdoc is not beautiful enough, you want to make further improvements, such as you want to change some comments to Chinese or other words, you want to join your logo, Or your contact information, replace it into a beautiful background pattern, is there a way to do? The answer is of course Yes, and it is very simple.
PHPDOC When the API document is output in the HTML format, uses PEAR IT, ITX module, which is a PEAR module similar to phplib's Templete.class, so you can easily customize and modify the default template to use you. .
We take a look at PHPDOC / renderer / html / templates: class.html classtree.html elementlist.html frame_packageelementlist.html frame_packagelist.html module.html modulegroup.html packagelist.html phpdoc.css warnings.html xmlfiles.html
You will see these files above, it's right, these are phpdoc templates used to generate API HTML. Now you can use your editor to modify these templates, here give basic modification principles: For {} circles The tag, these are some variables of the mark, at runtime, PHPDoc will replace the corresponding location with the actual variable. Therefore, you must keep all the variable tags, otherwise it will be wrong when you run. Take loop, in the middle of these 2 tags, will be used for loop output, so you are design When template, you should take into account the loop use, whether it will destroy your page's beautiful, such as: If the loop is in a table, you have to use
Reference
PHPDOC Home PHPDOC CVS
About Night Sailer: Beijing Said Data Co., Ltd. Engineer. Mainly engaged in the analysis and conversion of data, as well as related development work. Good at VB, Perl, PHP development and Linux's Chinese culture work. Recent interest is Perl, PHP and XML application, PHP's MVC development model, and Perl-gtk. You can contact him with E-mail: Nightsailer@hotmail.com.
