How to document your PHP class

Source: Internet
Author: User
Tags comments documentation generator php class php file php source code

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



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)


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.

Contact Us

The content source of this page is from Internet, which doesn't represent Alibaba Cloud's opinion; products and services mentioned on that page don't have any relationship with Alibaba Cloud. If the content of the page makes you feel confusing, please write us an email, we will handle the problem within 5 days after receiving your email.

If you find any instances of plagiarism from the community, please send an email to: and provide relevant evidence. A staff member will contact you within 5 working days.

A Free Trial That Lets You Build Big!

Start building with 50+ products and up to 12 months usage for Elastic Compute Service

  • Sales Support

    1 on 1 presale consultation

  • After-Sales Support

    24/7 Technical Support 6 Free Tickets per Quarter Faster Response

  • Alibaba Cloud offers highly flexible support services tailored to meet your exact needs.