| |
|
 |
In this article I will explain a method of documenting your PHP classes. This article is based on the eZ phpdoc generator.
|
|
A screenshot of the HTML class reference.
|
This article will show you a simple method of documenting your PHP classes. If you use the syntax I've described in this article, you can have nice looking reference documentation automatically generated for you. Go to phpdoc.ez.no to download the eZ phpdoc program. eZ phpdoc generates nice looking HTML class reference, a Lyx document and man pages for the classes. To see an example of generated documentation you can go to doc.ez.no.
A quick example
The code below gives you an example of how you can use the syntax of eZ phpdoc to document your classes. You have to put every class in a separate file, for eZ phpdoc to parse them correctly.
//!! Module Name
//! A brief description of the class
/*!
This is a more complete description of the class.
*/
class MyClass
{
/*!
This is the contructor of MyClass. It handles....
*/
function MyClass()
{
}
/// This is a variable description.
var MyVar;
} |
Comment List
| Topic: |
Author: |
Time: |
|
subclasses
|
Geoff Caplan
|
16.03.2001 22:18
|
|
Love the tool. I like the markup style, which is less intrusive than the javadoc style to my way of thinking.
The weakness, as I see it, compared to the main competition (www.phpdoc.de) is that ezphpdoc doesn't show the class hierarchy. If you get around to upgrading the script, perhaps you would consider adding this facility.
|
|
Good tool, need to discuss the specifics though
|
David Grinberg
|
21.02.2001 00:51
|
|
I think that after using this tool for a little while that it is an extremely good and powerful little tool. One that I will be using for all of my PHP documentation now.
I also like the tutorial very easy to read and gets straight to the point. Although I would like to point out some problems that I had and tok me a while to figure out.
1. Cannot have an index class in a file called index.php. As the generator puts the class list in a file called index.html and puts the documentation for the index class into index.html (copies the name of the php file.) These two then overwrite one another.
2. Cannot have a space before the declaration of the class. class needs to be the first character on the line, otherwise the tool cannot find the name.
3. There is no description of how to insert the version in the tutorial. Just need to check out the source code in th example.
Overall I love it. Keep up the good work!!
|
|
phpdoc
|
Ot Ratsaphong
|
28.11.2000 00:53
|
|
I am very impressed with this product. I especially like the ability to view the source code and the ability to switch back and forth b/w code and doco. Well Done!!!
One thing I found missing in the article were some recommendations on what information to put in the documentation. The examples show fairly rudimentary documentation.
We've got the tool to document our code, now let's see some examples of good documentation.
BTW your coding style is a great example to follow.
|
|
RE: phpdoc examples
|
Paul Kenneth Egell-Johnsen
|
28.11.2000 18:51
|
|
Check out http://doc.ez.no for our nightly updated php classes. These are documented using what we consider good style.
I will be the first, though, to admit that we haven't been very good at keeping it up, but rest assured, we will slowly get there.
|
|
|
|
|
