How to document your PHP class

How to document your PHP class

You have read about: Can Object-Oriented Programming help you manage your large web projects, and have you started to use PHP for Object-Oriented Programming? If you have compiled several types of applications on your website and you are a well-organized person, you should have compiled some documents about them. However, if you are an informal person like me, you will just add some comments in the class source code without any other documents. Without a document, it is difficult to remember the method name and their usage (parameters and meanings ). The most typical solution to this problem is to open the source code file and search for it from hundreds of statements. Documents similar to javadoc There should be a good way-if you have used the Java language, you will know the javadoc documentation system. This tool allows you to insert some tags in the source code file comments, which can be analyzed by the javadoc tool to generate a series of HTML pages to document your class. In this way, you can open a browser while programming and get a list of classes and classes with instructions. When developing a web application, this can be your reference to improve work efficiency and speed up development. My opinion is that maintaining a reference document in the source code is easier and more practical than maintaining an independent document, because this method is easier to keep updated. Otherwise, it will become very easy to get lazy and push the update of the document to an indefinite period (if you must add a deadline for it, I think it will be 10 thousand years ). On the contrary, when using a tool like this, only one workload is to update a tag near the source code you are modifying, and then run the tool to generate the updated HTML page again. Preview of some PHP document tools After learning about the above, I searched for available tools and found the following interesting tools: Phpsearchdoc is part of the enzyme project. As enzyme is a huge project, it needs to be documented. The developers there have compiled their own document systems and they are very generous in releasing them as an independent package. The obtained documents are first written to the database and then viewed by some PHP scripts, 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 searches for keywords from the source file, or even including comments. In fact, it happened to me that the 'function' word exists in my comments, and the result analyzer stupidly thinks that the word after the word is the name of the function. Unfortunately, I accidentally put a single quotation mark (') in the same row, and then I tried to write the data to the database. MySQL complained (an error occurred, because single quotes are used to split strings in MySQL ). In addition, it is quite difficult to install and run because it is still an Alpha test version. After all, it is more like a cross-reference generator than a document system. As I know, you cannot add your own annotations in functions and methods. Phpxref is more like cross-reference generation and processing than a real document system. Furthermore, it is more suitable for normal procedural programming than object-oriented programming. The goal of phpautodoc is to use PHP as javadoc applies to Java. It seems to be a perfect solution to meet my document needs. To test it, I have to compile the CGI version of PHP (I usually use the module version) because the generator is compiled in PHP. I may easily compile and install static execution programs in a Linux system. These commands can be used: 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 only part of it can work: it can only generate class documents (generate neat formats), but cannot generate summary. I don't know if it happened to happen on my machine, but it stopped when trying to generate a summary because of core dump (kernel crash) (PhP 4.0 pl2, RedHat 6.2 environment ). If PHP Execution version is installed on your machine/usr/local/bin, the syntax for calling it is (to get the result, I have to provide the full path of the PHP file and output directory) ./Phpautodoc-o Phpdoc is a PHP file used to maintain on the web site, and it is very suitable for distributed development. The document is generated from the database. After installation, you can use the Web interface to add your class to document it. This is indeed interesting, but it is a low-level maintenance method for separating documents from the source code, which is not very convenient for me. Common Tools After experiencing the setbacks of experimenting with all these tools but failing to succeed, until the pear project proposed a standard solution, I found a workable tool completely unrelated to PhP on the open source projects at Apple site. The project name is headerdoc. As the site said, "headerdoc is a tool for generating HTML reference documents from comments in the C or C ++ header files. It is written in Perl for ease of transplantation. Similar to javadoc, it allows developers to easily document their interfaces and output interface information to HTML. " Yes, you are right. headerdoc only supports C and C ++. There is no other language, but it is not like javadoc. Most of it depends on the markup written in the annotation, so you only need to make some small changes (I will explain it later) and it can be used well in PHP. These marks are very similar to javadoc. Some examples of headerdoc mark are @ class, @ function, and @ var. Document a class OK. Now let's go to details. First, let's take a look at how the next 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 frame on the left. The first thing to note is that the style used for opening comments is not exactly like javadoc comments/** (one slash and two asterisks), but replaced /*! (A diagonal line, an asterisk, and an exclamation point ). Tag usage is different, but they work in a similar way. For example, the first mark is the @ class mark, which is used to document a class, which follows the class name. The next tag is @ abstract tag, which It is an optional tag that describes the meaning of a class with a few words, and @ discussion tag is another optional tag for further discussion. Of course, it is up to you to decide whether to describe all things in the @ discussion mark or use @ abstract for processing. But remember that, in general, the more accurate the tag you use, the better the result. Documented functions or methods Use @ function to mark member functions or methods as documented. -------------------------------------------------------------------------------- /*! @ 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 cocould not be found */ -------------------------------------------------------------------------------- Document a method. @ Function mark declares a function followed by the function or member function name. Then you can use the @ abstract and @ discussion tags as before. However, there are two additional tags. @ Param indicates the parameter used to describe the function. The first word is assumed to be the name of the variable, and the others are arbitrary text descriptions. I suggest declaring the desired Variable type, even though PHP is not a strongly typed language. @ Result mark is used to describe the return value. Documented Variables Both variables and class variables are described using the @ var mark. In this tag, the first word is considered the name of the variable, and the others are arbitrary text descriptions. As before, it is recommended that you write the expected variable type. It is also a good idea to document all class variables. Document a class variable. -------------------------------------------------------------------------------- /*! @ Var idsession string-an unique session identifier */ VaR $ idsession; -------------------------------------------------------------------------------- Last contact -------------------------------------------------------------------------------- /*! @ Header myprojectname @ Abstract a virtual store to shop on Mars @ Discussion the difference [...] */ -------------------------------------------------------------------------------- @ Header flag is used to provide general information about documented projects or class groups. The @ header mark is followed by the project name, and can be supplemented with the @ abstract mark and @ discussion mark. Because Classes usually exist in different files (a file is a class, and it is a good idea to give the file name with the class name ), you may want to know where to put the @ header tag. The answer is surprising. My suggestion is: Put it in a separate file if it is long, or put it in front of the most important class if it is a short description. How to modify scripts for PHP The initial headerdoc script obtained from Apple is used for the C or C ++ header file, so you need to make some minor changes to it in PHP. If you are not interested in the details, you can download them from here and skip the following sections. The only thing you can do to modify the source program is to make the script accept the. php and. php3 Suffixes in the main perl file. -------------------------------------------------------------------------------- $ Diff headerdoc2html. pl/usr/local/bin/headerdoc2html 195c195 <($ Rootfilename = $ filename) = ~ S/. (H | I) $ //; --- > ($ Rootfilename = $ filename) = ~ S/. (H | I | PHP | php3) $ //; -------------------------------------------------------------------------------- Run scripts After the script is installed, assume that your class is placed under the classes subdirectory and you want to put the generated document under the docs directory. You should execute this command: Headerdoc2html-O docs classes/*. php Unfortunately, if there are multiple PHP files, this script has a bad habit of splitting those files into different directories, making browsing in class documents very difficult. And because the initial script is written for the C/C ++ header file (only class and function declarations are included in the header file without their definition ), the script outputs all the code under the function name until it encounters ";", so the first line of the Code is typical. But before you can easily read and feel desperate, relax, because I wrote a simple script to solve these two problems. -------------------------------------------------------------------------------- Cat classes/*. php | SED's/* {/; # {/G' | TR "#"" "> Docs/all. php Headerdoc2html-O docs/all. php Rm docs/all. php -------------------------------------------------------------------------------- If you want to know why I use the tr command instead of SED here, the reason is that SED 6.2, which is still used in RedHat 3.02, does not process line breaks. It should be replaced with the new version sed 3.02a. If you are interested in SED, read the sed faq. Good luck with the chemical industry of your documents!