How to document your PHP class
You have read about: Object-oriented programming can help you manage your large web project, and have you started using PHP to make object-oriented programming? If you have written a few classes on the website and you are a conditional person, then you should have written some documents about them. But if you are a person like I am not invalive, you just add some comments in the source code of the class without any other documents. There is no document that is difficult to remember the name of the method and their usage methods (parameters, and meanings). The most typical way to solve this is to open the source code file and find it from hundreds of statements. Similar to Javadoc's documents should have a good way - if you have used Java language, you will know the JavaDoc documentation system. This tool allows you to insert some tags in the source code file annotation, which can be analyzed by the Javadoc tool to generate a range of HTML pages to put your class documentation. So in programming, you can open your browser and get a class list and a list of classes with instructions. This can be your reference when you develop web applications, improve work efficiency and speed development. My opinion is to maintain a reference document as a source code to be easier and more practical than maintaining an independent document, as this method is easier to keep updates. Otherwise, it is very easy to become lazy to push the update to the document to indefinitely (if you must give it a period, I think it is 10,000 years). On the contrary, use a tool like this, only a little workload is updated near the source code you are modifying, then run the tool again generate the updated HTML page. Some PHP Document Tools The preview of the PHP Documentation After I learned it, I search for what is available, and I found some interesting tools: phpsearchDoc is part of the Enzyme project. Because Enzyme is a huge project, it needs to be documented. The developers there have been written their own documentation system and they are very generously published as a separate package. The resulting document is first written to the database, and then it can be viewed by some PHP scripts, like a dynamic Web site. From existing information, the logic separated by the analysis is quite good, however PHPSearchDoc (Version 1.01) does not have a real analyzer, but from the source file, even search keywords in the comment. In fact, I happened to me happen to existed in my annotation, and the results of the analyzer stupidly think that the word behind this word is the name of the function. More unfortunately, I can't put a single quotes (') in the same line, then I tried to write data into the database, MySQL made complaints (wrong, because single quotes were used in mysql to split strings ). And it is quite difficult because it is still an alpha beta. After all, it is more like a document system, it is a cross-reference generator, just as I know, you can't join your own comment in functions and methods. PHPXREF, like a real document system as a real document system, it seems to be more like a cross-reference. Furthermore, it is more suitable for normal procedural programming rather than object-oriented programming. PHPAUTODOC's goal is to implement as JavaDoc is used in PHP as Java. It looks a perfect solution to meet my document needs. In order to test it I have to compile PHP CGI version (I usually use the module version) because the generator is compiled with PHP.
I may easily compile and install a static executable under a Linux system, 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 only works: it can only generate a class's document (generated neat format), but cannot generate a summary. I don't know if this is just happening on my machine, but when trying to generate a summary because Core Dump (PHP 4.0 PL2, Redhat 6.2). If the PHP execution version is installed under your machine / usr / local / bin, calling it syntax is (in order to get the result I have to give the full path to the PHP file and output directory) ./phpautodoc -o phpdoc is one To maintain the PHP file on the Web site, and it is very suitable for distributed development methods. 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 that separates documents from the source code. This is not very convenient for me. The general tools have experienced all of these tools but not how successful setbacks, until Pear Project puts forward a standard solution, I found a work-free tool with PHP in Open Source Projects AT Apple site. The name of the project is HeaderDoc. As the site, "HeaderDoc is a tool for generating HTML reference documents from the annotation of C or C header files. It is written with Perl to port, which is similar to Javadoc, which allows developers to easily documentize Their interface and output the interface information to html. "Yes, you look like it, HeaderDoc only supports C and C . There is no other language, but it is not like Javadoc, which relies mostly to write tags in the comment, so as long as you do some small changes (I will explain later) can be used on PHP. These tags with javadoc are very elephant, some examples of HeaderDoc markers are @ Class, @ function and @var. Documentation a class OK, let us enter the details now. First let's take a look at how the class is documented. -------------------------------------------------- ----------------------------- / *! @Class bagitem @abstract an item in the shopping bag - IT is a shopItem with a SHOPITEM with QUANTITY @discussion a Bagtem Object May Be Constructed WITHOUT PREVIOUS Instantiation Of Neither ShopItem Nor Product * / ------------------------------- ------------------------------------------------- Document A class. The method of selecting the class on the left frame. The first thing you need to pay attention is to use the style in the open note. An exclamation mark).
The marking is also different, but they work in a similar manner. For example, the first tag is a @class tag, which is used for documentation, and this tag follows the name of the class. The next tag is an @abstract tag, which is an optional tag that describes a class's meaning, and the @Discussion tag is another optional tag for further discussion. Of course, you will be decided to describe all things in the @Discussion tag or use @abstract to process, but to remember, in general, the more accurate markers you use, the better the results. Documentation function or method member function or method uses the @Function tag to be documentized. -------------------------------------------------- ----------------------------- / *! @ABSTRACT GETS A Bagtem 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 be found * / - -------------------------------------------------- ---------------------------- Documentation. The @function tag declares a function and follows the function or member function name. Then you can use @abstract and @discussion tags like front. However, there are two additional tags. @Param tag for describing the parameters of the function; the first word is assumed to be the name of the variable, and the other is an arbitrary text description. I recommend that you want to declare the type of variable, although PHP is not a strong type of language. The @Result tag is used to describe the return value. Documentation variable variables or class variables are described using @var tags. In this tag, the first word is considered to be the name of the variable, while others are described as any text. As in front, I suggest writing that the desired variable type is a good practice. It is also a good idea of document all kinds of variables. Documentation a class variable.
-------------------------------------------------- ----------------------------- / *! @Var idsession string - an unique session Identifier * / var $ IDSESSION; -------------------------------------------------- ---------------------------------------------- -------------------------------------------------- ---------- / *! @Header myprojectname @abstract a virtual store to shop on mars @discussion the Difference [...] * / -------------- -------------------------------------------------- ---------------- @Header tag is used to provide some general information about the documentation or class group. The @Header tag itself follows the name of the project, and can be added with the @abstract tag and @Discussion tag. Because classes typically exist in different files (a file a class, and the name of the name to the file is a good idea), you may want to know where the @Header tag is. The answer is very surprised, which can be. My suggestion is: If it put it in a separate file, if it is a short description, put it in front of the most important class. How to modify the script for PHP from Apple's initial HeaderDoc script is used for C or C header files, so you need to do some small changes to it in PHP. If you are not interested in the details, you can download it from here and skip the bottom below. The unique thing to modify the source program is that in the primary Perl file, the script can be accepted .php and .php3 suffix. -------------------------------------------------- ------------------------------ $ DIFF Headerdoc2html.pl / usr / local / bin / headerdoc2html 195c195 <($ rootfilename = $ Filename) = ~ s /. (h | i) $ //; ---> ($ rootfilename = filename) = ~ s /. (h | i | php | php3) $ //; ----- -------------------------------------------------- ------------------------ Run the script after installation, assume that your class is placed in the classs subdirectory and you want to generate The document is placed in the DOCS directory, you should execute this command: Headerdoc2html -o docs class / *. PHP unfortunately if there are multiple PHP files, this script has a bad habit to split those files into different directories. It makes it difficult to browse in the document of the class.
