For a developer, documents are always one of the most vexing things. Also, it is likely that you will take 2 different attitudes towards the document:
When you use someone else's code base, the most desirable is its technical documentation, especially when the time is tight and you have to bite the bullet to read the jerky code.
When you write your own program, the last thing you want to do is write a technical document for it, and you'll excuse yourself for a variety of reasons: My code is clear enough to no longer have to rewrite the document for it ...
Perhaps to mitigate this paradox, there are a number of tools that can help you to automatically generate the appropriate API documentation by extracting the appropriate annotations from the source code. Pod2man in Javadoc,perl in Java. PHP, by contrast, seems to have lacked the tools it used to, but the situation has changed dramatically as Phpdoc continues to improve.
One of the first pear coding rules is that the annotation in the Pear program should be phpdoc converted. Thus, the role of phpdoc in pear is not small. Today, we'll talk about Phpdoc, this excellent pear program.
1. What is Phpdoc
Phpdoc is a very good module below pear, and its goal is to achieve a function like Javadoc that can quickly generate API documents with cross-references, indexes, and so on for your code. If you have used the documentation generated by Javadoc (such as JDK's documentation), you will know very well that if you have not used it, here is a screenshot of the Phpdoc generating its own document page:
As you can see from the diagram, the document generated by Phpdoc is very similar to Javadoc, and it has several indexing methods:
Packageindex: This is indexed according to the module
Classtree: This is based on the inheritance of your PHP class, you can generate a tree-like index
Modulegroups: This is divided by module
Elementlist: This is the alphabetical index of all your elements (class, method, process/function, variable)
2. Structure and function of Phpdoc
Since Phpdoc itself is a pear-compliant application, we first look at its structure. Phpdoc is all based on OOP, which is what Pear recommends, and how Phpdoc works:
Phpdoc scan the specified directory under the PHP source code, scan the keywords, intercept the annotation needs analysis, and then analyze the annotations of the special tag, generate the XML file, and then based on the analysis of the class and module information, build the corresponding index, generate XML file
For the generated XML file, use the custom template output as an HTML file.
In design terms, Phpdoc uses 2 super classes: Phpdocobject and Phpdocerror. This is the basic class of the entire Phpdoc, which is also recommended by pear, which means that when you write your own application framework, it is best to have a basic superclass, while other subclasses or functional classes have a common ancestor. In the process of scanning the source code, Phpdoc uses a form similar to grep, instead of using regular expressions as we normally think, he tried to use regular expressions, according to the author, but it was difficult to occupy and process the resources, so this unconventional form was used Specific implementation of interested readers can refer to the source code. I think Phpdoc is satisfying. On the other hand, the analysis results are saved in XML, which means that other applications can easily share this data, and Phpdco also provides the corresponding interface, you can implement this interface, the API documents to generate other forms, such as PDF, Latex,word and so on. At present, the results of phpdoc analysis can be expressed in HTML form, there may be more forms in the future. Even in HTML, because of the use of the template mechanism (which he uses with Pear's IT and ITX modules), you can easily make the style you want,
3. Phpdoc Foundation
Phpdoc is a document generated from the comments in your source code, so the process of annotating your program is the process of documenting it.
From this point of view, Phpdoc prompted you to develop good programming habits, as far as possible use of specifications, clear text for your program to make comments, and more or less also avoid the subsequent preparation of documents and document updates are not synchronized with some of the problems.
It is very important to compile annotations that conform to the Phpdoc specification, and to master this, you can basically use Phpdoc to work for you.
Notes are divided into document comments and Phpdoc comments in the
3.1 Documentation Comments
A document comment is actually a special form of multiline comment, usually placed in a particular keyword that you need to annotate (these keywords refer to those keywords that will be parsed by Phpdoc, and a list of related keywords, as described in section 4th below). The following is an example of a document annotation:
/**
* Common base class of all Phpdoc classes (briefly, 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 your can always inheritig Phpdoc classes from
* Class without any trouble. (Detailed description of the function)
*
* @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 documentation comments will produce the following documentation:
<b>PhpdocObject</b>
Phpdocobject
Common base class of all Phpdoc classes
<b>private class Phpdocobject </b>
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 classes to ThisClass without any trouble.
Authors ULF Wendel <ulf.wendel@phpdoc.de>
Version $Id: phpdocobject.php,v 1.3 2001/02/18 15:29:29 UW Exp $
3.2 Non-documented comments
If your comments are not placed in front of the keywords specified by the Phpdoc, then Phpdoc thinks that the comments you make are non document comments and will not be parsed by Phpdoc and will not appear in the API text you generate.
3.3 How to write your documentation notes
From 3.1 We can see that a document annotation is made up of 3 parts, namely: Functional description area, feature detail area, document marking area.
First, the first line is the sign "/**" with the start of a comment, then the carriage return, starting at line 2nd, is the functional description area, the feature description area begins with the indent "*", separated by a space between the body of the brief and the "*" number (note that in the document, all start with * and those * remain aligned indented formats). The body of the feature brief is typically a concise description of the function of the class, method, or function, and the body of the feature brief is displayed in the indexed area in the resulting document.
Behind the functional description area is an empty comment line, which is used to segment the summary area and the detailed description area. The feature detail area is also guided by the indentation ' * ', which is mainly about the function of your API, use, if possible, use examples, and so on. In this section, you should highlight the usual use of your API function or method, and indicate whether it is cross-platform (if it is involved), and you need to differentiate it from the generic information, usually by a different line, Then write notes on a particular platform or special information that should be sufficient so that your readers can write the appropriate test information, such as boundary conditions, parameter ranges, breakpoints, and so on.
After the feature detail area, it is a blank comment line. Then there is the document tag area where you can write related document tags (refer to the following section 4th for the use of these document tags), indicating some technical details, most notably the invocation parameter type, the return value extremely type, the inheritance relation, the related method/ Functions, and so on. Multiple document markers should use the same indentation to form a "tag block" for easy reading and analysis.
The line below the document Marker area is the comment end line "* *", note that the comment end tag/should be directly followed by a carriage return, do not attach other things, or may cause Phpdoc analysis error.
That's the basic way to write a document annotation, so let's discuss the specifications and techniques 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, which is, in layman's terms, "The information you tell me is exactly what I want to know." To do this, here are some tips and guidelines for writing documentation comments that you can help with:
Use <code> to flag keywords and naming and related code. If you need to refer to a keyword in a document, a variable name, or an example of a code that you want to give, you'd better use <code></code> to separate the keywords, variable names, and code snippets from your document so that when the reader reads, you will know that These will be running code, keywords rather than your descriptive language.
Use simple, clear language to avoid lengthy, complex, obscure long sentences to describe. Especially in the functional description, parameter description, such as the index part, try to use simple and clear language to reveal the main information, the other details in the detailed description of the section to elaborate. If you use English, it is advisable to use phrases rather than sentences.
If you use English, it is recommended to use the 3rd person singular form to illustrate
When giving a method a description of the function, you need to explain what the method "does" instead of "how". Therefore, it is recommended that your instructions begin with a verb, such as "return number of records", "delete a given record", and so on.
When you refer to an object or variable that is created from the current class, use "This" instead of "the" to refer to that object or to a variable
Avoid empty words, nonsense, for the API you want to give, after your API to have its functional description, is that it can "from the document." The so-called empty words, nonsense is that your description is not a functional description, but only the API name simple duplication and listing, or another API to explain the API, in the end, your readers do not know what you want to express the substance. Your description should be a supplemental message that is not visible from your class name, method name, or function name, rather than repeating your API name. A lot of people may have made this mistake unconsciously, including me, and here's an example:
/**
* Set up a user record set
*
* @param-Text given table name
*/
function Set_user_record ($table) {
What can you tell from the note above? Therefore, this annotation is actually nonsense, because you can see from the function name, the following is improved:
/**
* Open the System User table and set to the current user record set, which will be used for the default recordset for subsequent 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 appropriately. The name of the API referenced in your document (including your other classes and methods, PHP functions, etc.) adding appropriate links is very popular: you can use the @link tag to add links to the relevant APIs, but you don't need to add connections to all the APIs referenced in your document, Here's a simple standard: If users see an API in this place, they really want to click on it to get more information, which helps them understand your document, and even if you add a link, just add it when it first appears, and there's no need to add the same link again.
Because of Phpdoc's limitations, a PHP file defines only a class or module and does not place the class and module definitions in the same file, otherwise phpdoc may not work, at least for the current version. If your framework is built using OOP, avoid using modules or modular groups at the same time; at the same time you should carefully plan your application structure, your application framework should be a tree-like structure, the top of the branch not too much, for example, you can design 2 superclass, respectively, as a normal application and error handling of the Super class, The rest are derived from these 2 classes.
4. Phpdoc keywords and document labels
4.1 Key Words
class, function, Var, include (Include_once, require, require_once), define
The comments made earlier in these keywords are considered to be document comments.
4.2 Document Markers
Description: Use scope refers to keywords that the tag can be decorated with, or other document tags
@abstract Scope of Use: class, function, Var
Indicates that the current class is an abstract class.
Note: From the PHP language perspective, it does not support the concept of abstract classes, as Java,c++ does. There is also no corresponding keyword to decorate a class as an abstract class. Since Phpdoc is actually mostly based on Javadoc's approach, many document tags are also directly inherited from Javadoc, such as abstract,access,final and so on. Although these features are not supported at the language level, it is still recommended to follow these features 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 five-star pattern
* @abstract
*/
function Paint () {
;
}
}
@access (public|private) Scope of Use: class, function, Var, define, module
Indicates the access rights of this variable, class, function/method. If your function is used internally, you should indicate that it is private, the advantage of this is that even though PHP cannot prevent other people from using your private data, you can at least convey the message to your users that this is a proprietary function and therefore not guaranteed to remain in future releases; For @private data and methods, you should not use them directly, even if you can.
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 five-star pattern
* @abstract
* @access Public
*/
function Paint () {
;
}
}
@author Name [<email>] [, ...] scope: class, function, Var, define, module, use
Specify the author's information, followed by the author's name, email address, and other communication information. If there are multiple authors, use multiple @author in order to list them sequentially:
* @author Night Sailer <night@hotmail.com>
* @author Lee Tester <tester@gnome.org>
@brother (function () | $variable) Scope: class, function, Var, define, module, use
@sister (function () | $variable) Scope: class, function, Var, define, module, use
Indicate sibling classes, functions, or variables. These functions, classes, variables, and so on have similar information and implement the same functionality. For example, the number and type of parameters called and returned are the same, and the functionality implemented is the same. In this case, you can use @brother or @sister to indicate its sibling function without having to repeat the function of 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 five-star pattern
* @abstract
* @access Public
*/
function Paint () {
;
}
/**
* @brother paint ()
*/
function Draw () {
;
}
}
@const [ant] label [description] Scope of use: Define
Indicate constants
This tag is actually a constant used to illustrate the definition of PHP's define keyword.
@copyright Description Scope: class, Function, Var, module, define, use
Specify copyright information.
@deprec [ated] Label scope: class, Function, Var, module, define, use
Indicates information that is not recommended or discarded.
If one of your functions or methods has been replaced by a new function method, or has been discarded, you do not want the reader to continue to use it. Then you can use this flag to tell the reader that this function is reserved for compatibility only, it is not recommended, and if it has been replaced by other functions, point out the substitution.
Example:
/**
* Obsolete classes
*
* @deprec 1.5-2000/12/06
* @access Public
*/
function Dontusemeanymore () {
Print "Don" Use me no more. I have been deprecated. ";
}
@exclude Label scope: class, Function, Var, module, define, use
Indicates that the current comment will not be parsed and not appear in the text block
@final Scope of Use: class, function, Var
Indicates that this is a final class, method, property, and prohibits derivation, modification.
Example:
/**
* PI
* @final
*/
var $PI = 3.1415926;
@global (Object Objecttype|type) [$varname] [description] Scope of use: function
Indicates the global variables referenced in this function
Example:
/**
* Simuliert include_once in PHP 3.
*
* @global array $__used_files List of files already include
* @access Public
*/
function Include_once ($filename) {
Global $__used_files;
if (!isset ($__used_files["include_once" [$filename])) {
$__used_files["Include_once" [$filename] = true;
Include ($filename);
}
}
@include Description Usage: use
Indicates the information for the included file.
Example:
/**
* Abstract the definition of a drawing class.
*
* @includeFunction: _require_
*/
Require ("abstract.php");
@link URL Description Usage: class, function, Var, module, define, use
Defining an online connection, as mentioned in 3.4 above, you can use @link to add the appropriate online links.
For example: @link Http://www.phpdoc.de/PHPDoc Home
@magic description
This tag is not stated in Phpdoc, and the exact usage is still unclear.
@module Label Usage Scope: module
Defines the module information for the attribution, label is the name of the module, and functions with the same module name are grouped together in the index category. If you do not use OOP to write pear code, then it is recommended that you use this tag to collect related functions under the corresponding modules so that your overall framework is not too fragmented and confusing.
@modulegroup Label Usage Scope: module
The module group label that defines the attribution is the name of the module group, and if your application has a lot of modules, you can divide the different modules into corresponding modules according to the logical functions, so that your application framework can have a clearer logical relationship. This is for those who are not programming with OOP, if you use OOP, it is not necessary to use the concept of modular groups, because it is much better to use the form of "package-superclass-base-subclass" to represent your frame structure than to use "package-module Group-module".
@package Label Usage Scope: class, module
Defines the package information for the ownership, and the label is the name of the package. Classes in the name of the same package are divided together in the Final Document index. In fact, the package can also be understood as a different name space, although PHP does not have a name space concept, but you can put the relevant classes, modules belong to the same package, so that the equivalent of organizing a name space, of course, your application framework may have different packages, unfortunately, In this case, the syntax is not the namespace of the guarantee, you can only be artificially to avoid the different packages of functions or class names.
@param [Eter] (object objecttype|type) [$varname] [description] Use scope: function
Defines the parameter information for a function or method. This is the most commonly used document tag.
The Ojecttype is the object's class name, which indicates the type of the parameter, which can be of the following types:
String This parameter is a character type variable.
Array This parameter is an array.
Integer This parameter is a numeric type.
Integer (octal) This parameter is a numeric type and is stored in octal mode.
Integer (hexadecimal) This parameter is a numeric type and is stored in hexadecimal mode.
Boolean This parameter is a Boolean type.
Mixed the type of the parameter is variable and can be combined with several types above. However, the type of variable that can be accepted is generally described in subsequent instructions.
$varname is the name of the formal parameter
[description] is a description of the parameter.
If the function accepts more than one argument, follow it from left to right, followed by @param alignment, as shown in the following:
*
* @param array $tags array of tags returned by gettags
* @param array $data array where the allowed tags and their values are copied to
* @param array $allowed array of allowed (recognized) tags
@return (Object Objecttype|type) [$varname] Scope of use: function
Defines the return information for a function or method.
The type of the return information is the same as @param, $varname is the name of the returned variable, optional. The difference is that there is only one @return, not multiple @return
@see (function () | $varname | ( (Module|class)::) (function () | $varname)) [, ...]: class, function, Var, module, define, use
Define the functions and variables that need to be referenced, and add the corresponding super connections. This is also a more commonly used tag. 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, separated by commas in the middle.
The reference function, variable if it is the current class or module, then you can directly write the function, or the name of the variable, if it is a function to the function name followed by parentheses (), the variable name should be added $. Note that the so-called variable names here should also be described by you with @var, otherwise, Phpdoc will not be able to find the relevant reference and error.
If you want to reference a function of another class or other module, or a variable, then you can use the name of the function, the variable name, and the class or module as a range to indicate that the middle is delimited by::.
Here are some examples:
@see $run _time, $idle _time, $begin _time, $end _time
@see GetRuntime (), Getidletime (), Getbegintime (), Getendtime ()
@see time:: $run _time, Time::getbegintime ()
@since Label scope: class, Function, Var, module, define, use
Indicates which version of the API function or method was introduced.
@static Scope of Use: class, function, Var
Indicates that the variable, class, and function are static.
@throws exception [, exception] scope of use: function
Indicates an error exception that may be thrown by this function, which is most likely to occur
If you anticipate that there are conditions in this function that produce exceptions, then you can use the @throws tag to indicate what these exceptions are and when. For example, error reading a disk file, unable to connect to the database, network connection timeout or in some cases, you "intentionally" throw the exception and so on.
@todo scope: Class, function, module, use
Identify areas that should be improved or not implemented
@var [iable] (object objecttype|type) [$varname] [description] Use range: var
Define a description variable/attribute.
Object Objecttype|type Define the type of your variable, same as @param
$varname the name of the variable, you can use @see to refer to that name from somewhere else.
Description The description of the variable
@version Label scope: Class, function, module, use
Define version information.
You can of course write these versions manually, but Pear recommends you use the CVS $id tag to automatically label your version information. The form is as follows:
@version $Id
This way, when you checkout, CVS automatically expands to: @version $Id: phpdocparsercore.php,v 1.4 2001/02/18 14:45:27 UW Exp
5. Generate documentation
5.1 Installation Phpdoc
The installation Phpdoc is very simple, in fact because it has been released with PHP 4.05, so if your PHP is 4.05, then you will find Phpdoc this module under the Pear directory. If you don't find it, you can get a copy of the latest source code from Phpdoc CVs.
5.2 Running Phpdoc
Run Phpdoc need to do some preparation work, first of all to adjust your php.ini parameters,
Because Phpdoc runs longer than normal PHP applications, it is likely to exceed the maximum elapsed time that you define in php.ini (default is 30 seconds), according to the author's recommendation: piii,60 seconds, 120 seconds pii,240 seconds mmx200,480 seconds if the configuration is lower. If a timeout occurs, you can extend the values yourself appropriately.
Modify in PHP.ini:
;;;;;;;;;;;;;;;;;;;
; Resource Limits;
;;;;;;;;;;;;;;;;;;;
Max_execution_time = 480
Memory_limit = 8388608
If you do not want to or do not modify the php.ini permissions, then you can use the Set_time_limit () function to set this time, using the method: Set_time_limit (480); Set to start at this point and run for 480 seconds before timing out. Adding this function to the index.php can achieve the same effect as modifying the php.ini.
Second, you want to modify the index.php file below the Phpdoc directory:
Directory with include files
Define ("Phpdoc_include_dir", "c:/www/apache/doc/");
Change the "c:/www/apache/doc/" to your Phpdoc directory.
Important:set this to the linebreak sign of your system!
Define ("linebreak", "\ r \ n");
This is the definition of the symbol for line break, DOS below is a newline + carriage return, Unix below just enter can.
Next, do some customization work for your application to build the document:
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 with the name of your application.
directory where your source files reside:
$doc->setsourcedirectory (Phpdoc_include_dir);
Setsourcedirectory () Sets the directory of your application's PHP source file, replacing phpdoc_include_dir with your actual directory.
Save the generated docs here:
$doc->settarget (Phpdoc_include_dir.) apidoc/");
Settarget () sets the directory where your API documents are stored, Phpdoc generates XML and HTML files under this directory. Will Phpdoc_include_dir. " apidoc/"replace it with your own directory.
Use these templates:
$doc->settemplatedirectory (Phpdoc_include_dir.) Renderer/html/templates/");
Settemplatedirectory () Sets the directory of the templates used by HTML. If you need to use a custom template, you can use this function to set up the directory of your own template files.
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 needs to be analyzed, if you use a different extension, you need to add it here, for example if you have previous PHP3 files, you need to add:
$doc->setsourcefilesuffix (Array ("PHP", "Inc", "PhP3"));
This way, the basic customization work is done, now you can run index.php in the browser, and when you have the welcome message, it's time to start analyzing the document. The document parsing process will not be the same, depending on the machine's condition and the number of source code files analyzed. After the document analysis is finished, The browser displays the word finish, indicating that the analysis is complete, and you can find the analysis results, including HTML and XML files, below the directory you just specified.
5.3 Utility Tools
Though the Phpdoc index.php can produce documents, but it is not so convenient, here I gave a write the shell program Makeapidoc, you can use it to facilitate the production of your API documents, do not have to modify every time, do not have to start the browser to perform.
Usage is as follows: Makeapidoc-t your application title-s source Directory-D-build document repository Directory
Before using, 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 the PHPDOC directory, Phpbin is the path to the PHP executable file.
This program actually uses PHP as a shellscript, but it's used in bash, and PHP can actually run like a normal shell script, with the-Q argument, so it doesn't print the HTTP header.
6. Advanced: Custom Output documents
If you think the default Phpdoc generated HTML document is not beautiful enough, you want to make further improvements, such as you want to change some of the comments into Chinese or other text, you want to add your logo, or your contact, to a beautiful background pattern, there is no way to do it? The answer is, of course you can. , and very simple.
Phpdoc in the output HTML format API document, use is Pear's IT,ITX module, this is similar to phplib templete.class pear module, therefore, you can easily customize and modify the default template for your use.
Let's see phpdoc/renderer/html/templates:class.html classtree.html elementlist.html frame_packageelementlist.html first.
frame_packagelist.html module.html modulegroup.html packagelist.html phpdoc.css warnings.html
You'll see the files above, yes, these are the templates that Phpdoc use to generate API HTML, and now you can use your editor to modify these templates, and here are the basic principles of change:
For tags circled with {}, these are the tokens of some variables, and at runtime, Phpdoc will replace the actual variable values with the corresponding positions. Therefore, you must keep all the variable marks, otherwise the runtime will be wrong.
You should be aware that <!--Begin Xxx-loop--><!--end xxx-loop-->, and so on with loops, the middle portion of these 2 tags will be used for circular output, so you should consider recycling when designing templates. Whether it will destroy the beauty of your page, the simplest example: if the loop part is in a table, you want to use <tr> to separate the parts of the loop call, and should ensure that each <TD></TD> is matched close.
When you change the place is not small, you can also directly modify the style sheet phpdoc.css content, so that you can achieve the desired effect
You can store templates in different directories, set different template paths through Settemplatedirectory (), and generate API documents in different formats.
7. Reference Resources
PHPDOC Home
PHPDOC CVS
