Home arrow PHP arrow Page 6 - Writing Self-Documenting PHP Code

Different Strokes - PHP

Are you the kind of person who hates documenting your sourcecode? Does the thought of writing API documentation make your eyeballscontract and your toes itch? Well, itch no more - this articledemonstrates how you can use PHPDoc to automatically generate APIdocumentation using the comments in your source code.

TABLE OF CONTENTS:
  1. Writing Self-Documenting PHP Code
  2. Speaking In Tongues
  3. Drilling Deeper
  4. I, Robot
  5. Tonight's Menu
  6. Different Strokes
  7. Closing Time
By: Harish Kamath, (c) Melonfire
Rating: starstarstarstarstar / 14
April 15, 2002

print this article
SEARCH DEV SHED

TOOLS YOU CAN USE

advertisement
Now, while PHPDoc is a fairly cool little utility, it does come with some caveats. For one, the software is still in beta, and the author specifically notes that it may not work as advertised in all cases. Further, since the package is still under development, it's quite possible that there may be changes in future versions which are not backward-compatible. And finally, the program encounters difficulties if you include more than one class per PHP file.

If none of these things bothers you much, you should go ahead and begin using it. If, on the other hand, you're looking for alternatives, take a look at eZ phpdoc, a Perl-based auto-documentation utility created by the nice guys at eZ Systems (http://developer.ez.no).

I'm not going to get into the details of eZ phpdoc's syntax - there's a very good tutorial written by the author on that very topic at http://publish.ez.no/article/articleprint/29/ - but I will demonstrate a small example. Take a look:

<?php //!! SandwichMaker //! This class claims to make a sandwich for you automatically /*! One of the coolest inventions on the planet. class.Sandwichmaker allows you to specify your bread and filling, and then makes a plate of sandwiches matching your request. Ain't PHP cool? */ class SandwichMaker { /// bread type var $type; /// sandwich filling var $fillings = array(); /*! This function creates a sandwich with specified bread type and filling */ function makeSandwich() { // snip } /*! This function sets bread type for sandwich */ function setType($type) { // snip } /*! This function sets filling for sandwich */ function setFillings($fillings) { // snip } } ?>
As you can see, the syntax used by eZ phpdoc is different from that used by PHPDoc. Some users seem to find it easier; personally, though, I prefer the PHPDoc way of doing things. You should try both to see which one you're more comfortable with.

Once you've got your code all commented, you can use the eZ phpdoc Perl script to generate some documentation for it.

$ ./ezphpdoc-1.0.pl /usr/local/apache/htdocs/classes/ -o /tmp/docs/
Here's what it looks like:



Note that eZ phpdoc can currently output documentation in HTML, LaTeX and Unix manual formats.

 
 
>>> More PHP Articles          >>> More By Harish Kamath, (c) Melonfire
 

blog comments powered by Disqus
escort Bursa Bursa escort Antalya eskort
   

PHP ARTICLES

- Hackers Compromise PHP Sites to Launch Attac...
- Red Hat, Zend Form OpenShift PaaS Alliance
- PHP IDE News
- BCD, Zend Extend PHP Partnership
- PHP FAQ Highlight
- PHP Creator Didn't Set Out to Create a Langu...
- PHP Trends Revealed in Zend Study
- PHP: Best Methods for Running Scheduled Jobs
- PHP Array Functions: array_change_key_case
- PHP array_combine Function
- PHP array_chunk Function
- PHP Closures as View Helpers: Lazy-Loading F...
- Using PHP Closures as View Helpers
- PHP File and Operating System Program Execut...
- PHP: Effects of Wrapping Code in Class Const...

Developer Shed Affiliates

 


Dev Shed Tutorial Topics: