How to document your PHP class (i)
Author: Stefano Locati translation: Limodou
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.
Original Author: Limodou
Source: phpx
