NYCPHP Meetup

[Phil Powell]

patkins wrote:

>All,
>
>I'm trying this for the first time today. I downloaded and setup PHPDocumentor in under an hour. I commented a couple of classes, ran the web GUI and "Bing" there it was as beautiful as can be. 
>
>I am very impressed and motivated to clean up and comment all my projects. I also tried the "DOxygen" and "PHPDocumentor" was by far better.
>
>Cheers,
>Peter
>
>-----Original Message-----
>From: talk-bounces at lists.nyphp.org [mailto:talk-bounces at lists.nyphp.org] On Behalf Of Phil Powell
>Sent: Friday, February 27, 2004 12:59 PM
>To: NYPHP Talk
>Subject: Re: [nycphp-talk] Your experiences with PHPDocumentor
>
>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
>
>  
>
>>
>> 
>>
>>    
>>
>
>
>  
>
Cool, help me then, I'm stuck!

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