How to document your PHP class

Have you read about: Object-oriented programming can help you manage your large Web projects, and have you started using PHP for object-oriented programming? If you've written several classes of apps on the site and you're a methodical person, you should have written some documentation about them. But if you're a sloppy person like me, you just add a few notes to the source code of the class and no other document. Without documents, it is difficult to remember the name of the method and how they are used (parameters and meanings). The most typical way to solve this situation is to open the source code file and find it from hundreds of statements.

Documentation similar to Javadoc
There should be a good way----if you have ever used the Java language, you will know the Javadoc documentation system. This tool allows you to insert tags in the source code file comments that can be parsed by the Javadoc tool to generate a series of HTML pages to document your class. In that way you can open the browser and get a list of class lists and class methods with instructions while you are programming. When you develop Web applications, this can be your reference, improve productivity and speed development.

My opinion is that maintaining a reference document as a source code is easier and more useful than maintaining a separate document because it is easier to keep up to date. Otherwise it's very easy to become lazy so that updates to the document are deferred to an indefinite period (if you have to add a deadline, I think it's 10,000 years). Instead of using a tool like this, there is only a little effort to update a tag near the source code you are modifying, and then run the tool again to generate the updated HTML page.

A preview of some PHP document tools
After I learned about it, I searched for what was available, and I found some interesting tools as follows:

Phpsearchdoc is part of the enzyme project. Because enzyme is a huge project, it needs to be documented. Developers there have written their own document systems and they are very generous to publish them as a separate package. The resulting document is first written to the database, and can then be viewed by some PHP scripts, like a dynamic web site.

The idea of separating the logic used for analysis from existing information is quite good, but Phpsearchdoc (version 1.01) does not have a real parser but searches for keywords from source files and even comments. In fact, it happened to me that there was a ' function ' word in my comment, and the parser foolishly assumed that the word behind the word was the name of the function. Unfortunately, I accidentally put a single quote (') on the same line, and then I tried to write the data to the database, and MySQL complained (because single quotes were used to split strings in MySQL).

And it's pretty difficult to install and run because it's an alpha beta. After all, it's more like a cross-reference generator than a document system, as I know you can't add your own annotations to functions and methods.

Phpxref, as the name implies, looks more like a cross-reference-oriented generation process than a real document system. Further, it is better suited to normal procedural programming than object-oriented programming.

The goal of Phpautodoc is to implement PHP as Javadoc applies to Java. It looks like a perfect solution for my document needs. In order to test it I had to compile the CGI version of PHP (I usually use the module version) because the generator was compiled in PHP. I could easily compile and install static execution programs on a Linux system, and you can use these commands:

RM Config.chche
Make clean
./configure
Make
CP Php/usr/local/bin

I decided to test its own PHP source code, and I found that it was only partially working: it was able to generate only the document of the class (a neat format), but not the summary. I don't know if this just happened on my machine, but when I tried to generate a summary it stopped because of core dump (the kernel crashed) (PHP 4.0 pl2,redhat 6.2 environment). If the PHP version is installed under your machine/usr/local/bin, the syntax for calling it is (I have to give the full path to the PHP file and output directory to get the result)

./phpautodoc-o

Phpdoc is a PHP file to maintain on a Web site, and it is ideal for distributed development. The document is generated from the database, and after installation, you can use the Web interface to increase the documentation of your class. This is really interesting, but it is a low-level maintenance method of separating documents from source code, which is not very convenient for me.

Common tools
After being tested for all of these tools without getting any success, until Pear Project presents a standard workaround, I found a working tool that was completely unrelated to PHP at the open Source Projects at the Apple site. The name of the project is Headerdoc. As the site says, "Headerdoc is a tool for referencing documents that generate HTML from comments in a C or C + + header file." It is written in Perl for easy porting. Similar to Javadoc, it allows developers to easily document their interfaces and output interface information to HTML. "

Yes, you see right, Headerdoc only supports C and C + +. There's no other language, but it's not like Javadoc, which relies heavily on tags written in annotations, so just make minor changes (I'll explain later) to be good for PHP. These tags are similar to Javadoc, and some examples of headerdoc markers are @class, @function and @var.

Document A class
OK, let's get into the details now. Let's first look at how a class is documented.

--------------------------------------------------------------------------------
/*! @class Bagitem
@abstract an item in the shopping bag-it be a shopitem with quantity
@discussion A Bagitem Object may constructed without previous
Instantiation of neither Shopitem nor Product
*/
--------------------------------------------------------------------------------

Document A class. You can select a method for the class on the left frame.

The first thing to note is that the style used on the open annotation is not exactly like the Javadoc annotation/** (a slash and two asterisks), but instead the/*! (a slash, an asterisk and an exclamation point). Tags are used differently, but they work in a similar way. For example, the first tag is the @class tag, which is used to document a class, which follows the name of the class. The next tag is the @abstract tag, which
is an optional tag that describes the meaning of a class with a few words, while the @discussion tag is another optional tag for further discussion. It's up to you to decide whether to describe everything in the @discussion tag or to use @abstract, but keep in mind that, in general, the more accurate the tag you use, the better the result.

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!