PEAR: use PHPDoc to easily create your PEAR document

Article title: PEAR: use PHPDoc to easily create your PEAR document. Linux is a technology channel of the IT lab in China. Includes basic categories such as desktop applications, Linux system management, kernel research, embedded systems, and open source.
　　 1. what is phpdoc?
PHPDoc is an excellent module under PEAR. it aims to implement functions similar to javadoc and quickly generate API documents with mutual reference and indexing functions for your code. If you have used documents generated by javadoc (such as jdk documents), you will be very clear that if you have not used them, the following is a phpdoc to generate its own document page:
　　
As you can see from the figure, the documents generated by phpdoc are similar to those generated by JAVADOC. it has multiple indexing methods:
Packageindex: this is indexed by module Classtree: this is based on the inheritance relationship of your php class, you can generate a tree index Modulegroups: this is divided by module
Elementlist: this is the alphabetic index of all your elements (class, method, process/function, variable)
　　
　　 2. phpdoc structure and functions
Because phpdoc is also a pear-compliant application, let's first understand its structure. Phpdoc is all written using the idea of OOP, which is also recommended by PEAR. The working principle of phpdoc is as follows:
　　
Phpdoc scans the php source code under the specified directory, scans the keywords, captures the comments to be analyzed, analyzes the specific tags in the comments, and generates xml files, then, based on the analyzed class and module information, create an index to generate an xml file.
For generated xml files, use a custom template to output them as html files.
　　
In terms of design, phpdoc uses two superclasses: PhpdocObject and PhpdocError. This is the basic class of PHPDOC. this method is also recommended by PEAR. that is to say, when you write your own application framework, it is best to have a basic superclass, other subclass or function classes share a common ancestor. During source code scanning, PHPDOC uses a format similar to GREP, which is not implemented using regular expressions as we usually think. according to the author's explanation, he has tried to use regular expressions, but the resource occupation and processing speed are difficult to satisfy. Therefore, this unconventional form is adopted. for specific implementations, please refer to the source code. I think PHPDOC is satisfactory. on the other hand, the analysis results are saved in XML format, which means that other applications can easily share the data and PHPDCO also provides corresponding interfaces, you can implement this interface to generate other forms of API documents, such as PDF, LATEX, and WORD. Currently, PHPDOC analysis results can be displayed in HTML format, and more forms may be available in the future. Even in the HTML format, the template mechanism (which is implemented by PEAR's IT and ITX modules) allows you to easily customize the style you need,
　　
　　 3. PHPDoc basics
PHPDoc generates a document from the comments of your source code. Therefore, the process of commenting your program is the process of compiling the document.
　　
From this point on, PHPdoc prompts you to develop good programming habits, try to use specifications, clear text for your program to make comments, at the same time, it also avoids the problem of non-sync preparation of documents and updates later.
　　
It is very important to compile comments that comply with the PHPDoc specifications. after understanding this, you can basically use PHPDoc to work for you.
　　
Annotations are classified into document annotations and non-document annotations in PHPDoc.
　　
3.1 document comment
Document comments are actually some special forms of multi-line comments, which are usually placed in the specific keywords you need to comment on (these keywords refer to the keywords that will be analyzed by phpdoc, for a list of related keywords, see the description in section 4th. The following is an example of a document comment:
/**
* Common base class of all phpdoc classes (brief description, used 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 constructor,
* So you can always inheritig Phpdoc classes from this
* Class without any trouble. (detailed function description)
*
* @ Author Ulf Wendel
* @ Version $ Id: PhpdocObject. php, v 1.3 2001/02/18 15:29:29 uw Exp $
* @ Package PHPDoc (document mark)
*/
Class PhpdocObject {
.....
}
　　
The preceding document notes generate the following documents:
　　 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
Constructor, so you can always inheritig Phpdoc classes 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 comments
If your comments are not placed before the keywords specified by phpdoc, phpdoc considers the comments you have made to be non-document comments and will not be analyzed by phpdoc, it will not appear in your generated api text.
　　
3.3 How to write your document comments
From 3.1, we can see that a document annotation consists of three parts: the function description area, the function description area, and the document marking area.
　　
First, the first line is the sign of the beginning of the comment "/**", and then press Enter. starting from row 2nd, it is the function description area, the function description area starts with an indented "*" and is separated by spaces between the body of the description and the "*" number. (Note that in this document, it starts, and these * Keep the aligned indent format ). The body of the function description is a brief description of the class, method, or function. The body of the function description is displayed in the index area in the generated document.
　　
The description area is followed by an empty comment line to separate the description area and detailed description area. The detailed description area of the function is also guided by the indent '* ". This section mainly describes the functions and usage of your API. if possible, it can also be used as an example. In this section, you should focus on the common usage and usage of your API functions or methods, and specify whether it is cross-platform (if involved). For platform-related information, you need to treat it differently from general information. the common practice is to set up another line, and then write the precautions or special information on a specific platform. This information should be sufficient, this allows your readers to write test information, such as boundary conditions, parameter ranges, and breakpoints.
　　
In the detailed description area, there is a blank comment line, followed by the document tag area, you can refer to section 4th next to these document tags to specify some technical details. The most important thing is to call the parameter type, the returned values are of extremely type, inheritance, and related methods/functions. Multiple document tags should use the same indentation to form a "tag block" for easy reading and analysis.
　　
The line below the document tag area is the comment end line "*/". Note that the comment end mark */should be followed by a carriage return directly. do not add anything else, otherwise, PHPDOC analysis may fail.
　　
The above is the basic method for writing a document annotation. next we will discuss the specifications and skills for writing a document.
　　
3.4 document writing guide
When you describe the purpose or function of your code, it is best to follow the habits of most people. Generally speaking, "the information you tell me is exactly what I want to know ". To this end, we will introduce some notes writing skills and specifications, and hope to help you:
　　
Use To mark keywords and names and related code. If you need to reference some keywords, variable names, or code examples in this document, you 'd better useTo separate these keywords, variable names, code snippets, and your documents. as a result, the reader will know that these will be running code, keyword instead of your descriptive language.
Use simple and clear languages to avoid lengthy, complex, and obscure long sentences. Especially in the function description, parameter description, and other index sections, try to use a simple and clear language to reveal the main information and put other details in the detailed description section. If you use English, we recommend that you use phrases instead of sentences.
If you are using English, we recommend that you use the 3rd person-in-person singular format.
When explaining methods and functions, you need to explain what this method has done, rather than how it is done ". Therefore, we recommend that you start with a verb, such as "number of returned records" and "delete a given record.
When the referenced object or variable is created from the current class, use "this" instead of "the" to refer to the object or variable
Avoid empty talk and nonsense. for the API you want to provide, you need to have its function description after your API, which is its ability to "self-document ". The so-called nonsense means that your description is not a function description, but a simple repeat and listing of API names, or you can use another API to explain this API. In the end, your readers do not know the content you want to express. Your description should be supplemental information that is invisible to your class name, method name, or function name, rather than repeating your API name. Many people (including me) may make this mistake without knowing it. The following is an example:
/**
* Set a user record set
*
* @ Param text specifies the table name.
*/
Function set_user_record ($ table ){
　　
What do you know from the above comments? Therefore, this comment is actually nonsense, as you can see from the function name. The following is an improved one:
/**
* Open the System User table and set it to the current user record set. this record set is used as the default record set for subsequent user data update operations. If it fails, a database error is thrown.
*
* @ Param text name of the system user table to be opened.
*/
Function set_user_record ($ table ){
　　
Use links as appropriate. It is very popular to add appropriate links to the API name referenced in your document (including your other classes and methods, PHP functions, and so on: you can use the @ link Tag to add links to related APIs. However, you do not need to add connections to all the APIs referenced in this document, here is a simple standard: If you see an API