document for php classes

qhyang

Hi,

I'm looking for a document tool that I can use to document my PHP classes. It should work like Javadoc and can generate HTML documents for class, member variables of a class and methods of a class, etc.
Any free good tools outthere for windows 2000 environment?

Any help is appreciated. Thanks!

Joan

van__

Dont' know if there are...
but you can look over at phpclasses.org
for some existing classes.

I was planning on extending my current template parser to doc my templates and classes anyway.

JavaDoc uses / comments here / to designate a document comment

so...

preg_match_all('/\/+[]{2}(.[]+)[*]{2}\/+/',$file,$comments);

will produce an array called comments that will contain the text portion (no /**'s) in the array element $comments[1]

You can of course further parse those comments, I'd recommend using a standard systax, preferably XML based to hold comment section inside, which can then be XSLT'd to HTML

van__

Oh... I totally messed up that regex. The asterisks are special.

preg_match_all('/\/+[*]{2}(.[^{*]+)[*]{2}\/+/',$file,$comments);}

... is correct.
me needs more coffee I think 🙂

Anon

I developed a really simple way of documenting my classes for a recent LARGE project.

With each function of each class, and at the beginning of each class, I would add a comment like such..

//##"type","func_name","num_args","class_member_of","inherits","desc","example"

Here is a breakdown of each field.

type - denoted whether it was a function or class comment.
func_name - stores the name of the function or class.
num_args - Is the number of arguments it accepts
class_member_of - Is the name of the class it is a memeber of.
inherits - are any classes that it might inherit properties from
desc - a description of what the class does
example - An example of usage

I then have a perl script that parses all this info out, and builds a pretty complex hash of the structure of the classes. I then jam it into a DB. The class doumentation is now browsable! I also containerized each function between two comments

//####function_name
function function_name (){
//##"type","function_name","num_args","class_member_of","inherits","desc","example"
print "hey";
}
//####function_name

This allows for people to drill down on a link and do a pass-thru view of the actual code of the function.

Anytime new code or comments were added, just re-run the perl script and the DB was updated.

van__

Nice, not what I had in mind though.
Have have a software library of over 20 core object componants that will be updated periodically. THe library is capable of supporting multilple sites simultaneously, as in 1 source distribution can service as many sites as the server can hold.

My needs are a bit more robust and since I am breaking away from servicing my clients on an ongoing basis and focusing on my own projects, they will be using other developers to operate my software, which is binary PHP modules, so they cannot just read the source (heh heh heh) and thus need to understand the very elaborate API I have built.

Your's is similar as I was envisioning placing beginning and end flags for each function, or even just looking for each declaration of a function and going that route, as a PHP class format is pretty simple to parse.

But I need hefty documentation for each class and each class method as that will be their only guiding light into understanding how to use the API.

Which is why I was opting for an XML approach.

....

<OBJECT_METHOD NAME=$METHOD_NAME TYPE=set('CONTRUCTOR'|'METHOD'|'SUB_ROUTINE')>
<METHOD_ARG NAME=$ARG_NAME TYPE=$TYPE>

....

</OBJECT_METHOD>

....
</OBJECT>

As you can see from that very very brief example is that I can actually make a data definition based upon a schema and use that to validate all documentation against it, that ensures that all required pieces are in place and all data types are correct.
Additionally, I can be very detailed and being XML, it is maleable as I may use XSLT to transform to HTML as well as just parsing it straight on out to an RTF file or even a txt file... or just leave it as XML and let the end user parse it as they please.

And of course, I can stuff each XML item into a database for speedy retrieval 🙂