How to document your PHP classes (1)_PHP Tutorial

How to document your PHP classes (1)


Author: stefano Locati Translation: limodou


You have 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 to use on your website and you're an organized person, you should have written some documentation about them. But if you are a casual person like me, you will just add some comments in the source code of the class without any other documentation. Without documentation it is difficult to remember the names of methods and how to use them (parameters and meanings). The most typical solution to this situation is to open the source code file and search through hundreds or thousands of statements.


Javadoc-like documentation

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 source code file comments, which can be analyzed by the Javadoc tool to generate a series of HTML pages to document your classes. That way you can have your browser open while you're programming and get a list of classes and a list of class methods with descriptions. When you develop web applications, this can become your reference, improve work efficiency and speed up development.


My opinion is that it is easier and more practical to maintain a reference document within the source code than to maintain a separate document, because this method is easier to keep updated. Otherwise it's very easy to get lazy and postpone updates to the document indefinitely (if I had to put a time limit on it, I'd say 10,000 years). Instead using a tool like this, the only effort is 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 documentation tools

After understanding the above, 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. The developers there have written their own documentation system and they've been generous enough to release it as a standalone package. The resulting document is first written to the database and can then be viewed by some PHP script, like a dynamic web site.


The idea of ​​separating the logic used for analysis from the existing information is quite good, however phpSearchdoc (version 1.01) does not have a real analyzer, but from the source file, even including comments Search for keywords. In fact, it happened to me that the word 'function' was present in one of my comments, and the parser foolishly thought that the word following this word was the name of the function. Even more unfortunately, I happened to put a single quote (') on the same line, and then I tried to write the data to the database, and mysql complained (an error occurred because single quotes are used to separate strings in mysql ).


And it is quite difficult to install and run because it is still an alpha test version. After all it's more of a cross-reference generator than a documentation system, and as I know, you can't add your own comments to functions and methods.


phpxref, as the name suggests, seems more like a cross-reference generation process than a real documentation system. Furthermore, it is more suitable for normal procedural programming rather than object-oriented programming.


The goal of phpautodoc is to be used for PHP like Javadoc is for Java. It looked like the perfect solution for my documentation needs. To test it I had to compile the CGI version of PHP (I usually use the module version), since the generator is written in PHP. I can easily compile and install static executables on a Linux system using these commands:


rm config.chche

make clean

. /configure

make

cp php /usr/local/bin


I decided to test it with its own PHP source code, and I found that it only partially worked Working: It can only generate documentation for classes (generating neat formatting), but not summaries. I don't know if this just happened to happen on my machine, but it stopped with a core dump when trying to generate the summary (PHP 4.0 pl2, RedHat 6.2 environment). If the PHP executable version is installed on your machine/usr/local/bin, the syntax to call it is (in order to get the result I have to give the full path of the php file and output directory)


./phpautodoc -o


phpdoc is a php file used to maintain on a Web site, and it is very suitable for distributed development. Documentation is generated from the database; after installation, you can use the web interface to add your classes to document them. This is indeed interesting, but it is a low-level maintenance method that separates documentation from source code, which is not very convenient for me.


Universal Tools

After the frustration of trying all these tools without much success until the Pear Project came up with a standard solution, I found a working tool that had absolutely nothing to do with PHP at the Open Source Projects at Apple site . The name of the project is HeaderDoc. As the site says "HeaderDoc is a tool that generates HTML reference documentation from comments in C or C++ header files. It is written in Perl for portability. Similar to JavaDoc, it allows developers to easily document Their interface, and output the interface information to HTML "


Yes, you read it right, HeaderDoc only supports C and C++. No other language, but unlike JavaDoc, it relies mostly on markup written in comments, so it can work well with PHP with just a few minor changes (which I'll explain later). These tags are very similar to JavaDoc. Some examples of HeaderDoc tags are @class, @function and @var.


Documenting a class

OK, let’s get into the details now. First let's look at how a class is documented.


----------------------------------------- ---------------------------------------

/*! @class BagItem

@abstract An item in the shopping bag - it is a shopitem with quantity

@discussion A BagItem object may be constructed without previous

instantiation of neither ShopItem nor Product

*/

---------------------------------------- -----------------------------------------------


Document a class. You can select the class method in the left frame.


The first thing to note is that the style used to open comments is not exactly like the JavaDoc comment /** (one slash and two asterisks), but replaced by /*! (a slash, an asterisk and an exclamation mark). The tag usage is also different, but they work in a similar way. For example, the first tag is the @class tag, which is used to document a class. This tag is followed by the name of the class. The next tag is the @abstract tag, which

is an optional tag that describes the meaning of a class in a few words, while the @discussion tag is another optional tag used for further discussion. It's of course up to you to decide whether to describe everything in @discussion tags or use @abstract to handle it, but keep in mind that, in general, the more precise the tags you use, the better the results.


Original author: limodou

Source: PHPX

http://www.bkjia.com/PHPjc/364121.htmlwww.bkjia.comtruehttp: //www.bkjia.com/PHPjc/364121.htmlTechArticleHow to document your PHP classes (1) Author: stefano Locati Translation: limodou You have read about: Oriented Object programming can help you manage your large web projects and you're already starting...