NYCPHP Meetup

[Dave Callaghan]

> >>>general response to all Phil Powell responses, top-posted for stand-alone convenience:
This is actually why I recommend taking phpDocumentor one step at a time: its very full featured! You can get pretty good results from just a very basic initial implementation. 

If something chokes, dump it until you get a clean output. Bad documentation is worse than no documentation. If you don't understand something, its probably because you don't need it right now. And later, as you get used to it, you'll start asking yourself 'why can't it ....'. Then you'll probably find out that it does. I had that [blank stare altogether] feeling many times with this tool (still do). But luckily, the advanced tags just aren't necessary right away, if ever.

Even if you had good result with Doxygen, which appears to be a fine tool, I would still recommend you stick it out with phpDocumentor, if for no other reason then its positioned to become something of a standard. If for no other reason than PEAR uses it.

One final thing. Most people find that their coding style changes once they start structured documentation. I make people in my team write out all the classes with all the documentation BEFORE they start coding. The end result is that we get good code complete faster.

Good luck!

> Dave Callaghan wrote:
> 
> >>>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.
> >
> 
> Thanx.. I'm at that page now and trying to figure it out is like trying 
> to learn Mongolian in an hour.  I am not fathoming most of it, though I 
> understand some of the tags like @accept, @param and @return, easy ones. 
>  @global throws warnings and @package just plain chokes the 
> phpdocumentor tool.
> 
> >
> >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.
> >
> 
> I am not sure what I am. The bastard child of OO and procedural code.  I 
> create PHP scripts that are flat-procedure ("index.php") that require 
> ".inc.php" library scripts that contain a boatload of classes and 
> subclasses.  My programming style which I don't think there is a 
> category for.
> 
> I have a limited understanding of "javadoc" albeit new but way WAY 
> easier than this!  
> 
> >
> >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.
> >  
> >
> each object, why?  I have one file containing 15 - 20 classes each, each 
> class averaging about 5 methods per class, each method averaging 4 
> globals and 10 - 15 local variables.  And about 5 files structured like 
> that per project per client.  So why do each object, should I not just 
> have one DocBlock with author, version and package and then each method 
> I document vars, params and optional returns?
> 
> >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.
> >  
> >
> 
> Just my luck my HTML interface throws PHP code all over the place along 
> with HTML.  Hard to read but I'm muddling through here.
> 
> >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.
> >  
> >
> 
> [blank stare altogether]
> 
> >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. 
> >
> >
> >
> >
> >
> >
> >  
> >
> 
> thanx for the detailed tips.. this will take more than one day to be 
> able to use just for one file, which I'm experimenting with.  I gave up 
> on DOxygen, it's even harder for me to use than PHPDocumentor.
> 
> Phil
> 
> >
> >
> >
> >  
> >
> 
> 
> -- 
> Phil Powell
> Web Developer
>   ADNET Systems, Inc.
>   11260 Roger Bacon Drive, Suite 403
>   Reston, VA  20190-5203
> Phone: (703) 709-7218 x107   Cell: (571) 437-4430   FAX: (703) 709-7219
> EMail:  Phillip.Powell at adnet-sys.com      AOL IM: SOA Dude
> 
> 
> 
> 
> 
> _______________________________________________
> talk mailing list
> talk at lists.nyphp.org
> http://lists.nyphp.org/mailman/listinfo/talk

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

Powered by Outblaze