NYCPHP Meetup

[Dave Callaghan]

> >Phil Powell writes:
> Sorry but that tells me little-to-nothing.  You haven't told me about 
> ease of use, code manipulation to make it work for documenting, all I 
> see is the results of using Doxygen.  I'd like to know how easy it was 
> for YOU to use it, implement it, examples of *HOW* you used it in a case 
> of like a flat script here or a class method there, anything.
> 
> I am struggling with PHPDocumentor because it seems, at best, impossible 
> to use.
I use phpDocumentor in all of my OOP projects and I document the code with phpDocumentor in much the same way as I use JavaDoc. I found the concept familiar, the syntax simple and the need clear so your statement that 'PHPDocumentor because it seems, at best, impossible to use' tells me little-to-nothing.

First, in order to use phpDocumentor, you need to read the 'phpDocumentor Guide to Creating Fantastic Documentation' at http://phpdoc.org/docs/HTMLSmartyConverter/default/phpDocumentor/tutorial_phpDocumentor.pkg.html
In all honesty, if you read it an it didn't help you, read it again. Not suprisingly, the documentation for phpDocumentor is done very well. If you aren't familiar with structured code documentation (and many, many experienced programmers are not) you may have just skimmed the text because you trivialized the task. Good documentation is hard.

For another point of view on this type of code documentation, or 'literate programming' as people who need to call things something call this thing, read the 'The Design of Distributed Hyperlinked Programming Documentation' at 
ftp://ftp.java.sun.com/docs/javadoc-paper/iwhd.pdf  This will give you a perspective on what the developers of Javadoc, and thus by extension phpDocumentor, are trying to do.

I only document OPP code because I only write OOP code because that's the coding methodology that my projects are usually best served by. If you are a proceduraral programmer, I imagine phpDocumentor will still help by I can't speak from experience. Remember, since this is heavily inspired by JavaDoc, it natually lends itself to OOP.

Alway fully document each object with author, version, date tags, etc. (An example of etc might be copyright) For each class, provide scope and variable type tags as well as short and long description. A short description is one sentence followed by a period and a line break. Document methods like classes except provide parameter information. For each variable, provide scope and variable type tags.

If you just go this far, you will be able to produce suprisingly helpful documentation. Unless you are working for a company that already has existing documentation standards in place, you should be fine. Better than fine, actually.

The last step is to actually produce the phpDocumentor document. The command-line tool is very powerful. Use the web tool anyway. The docbuilder interface can be accessed via index.html in the install directory of phpDocumentor, or the docbuilder subdirectory. Its slick, easy and will do the job right the first time. You can save the command-line for those cold winter nights.

Once you have your code documented to this point, you have reached a milestone. Now you can explore more of the functionality of phpDocumentor. I recommend learning how to use templates for no ther reason than the typical reason one uses templates: less work = more gooder. Not that it isn't great fun copying the same scope and variable documentation on type of fifteen class-level variables, but templates are a good thing to learn. The same goes for packages. I'm still not sure why, but the @package tag usage does seem to cause some confusion. The same is true of the @see tag. But once you get these tags, you'll love them

Its a good idea now to look at ALL of the tags offerend by phpDocumentor. I'm a big fan of the @todo tag. Include the @version $Revision$ tag and udate it with CVS version.

Finally, experiment with outputting you phpDocumentor into different formats. I'm now a big fan of outputting my documentation into a PEAR template, but that's because I'm a big PEAR fan. If you prefer DocBook, that also makes perfect sense. If you like more than one, now it may be time to learn the command-line interface and write a script. There are many, many tags in phpDocumentor and you will probably like some of them and want to include them. 










-- 
______________________________________________
Check out the latest SMS services @ http://www.linuxmail.org 
This allows you to send and receive SMS through your mailbox.

Powered by Outblaze