PHP
  Home arrow PHP arrow Page 6 - Writing Self-Documenting PHP Code
Dev Shed Forums  
Administration  
AJAX  
Apache  
BrainDump  
DHTML  
Flash  
Java  
JavaScript  
Multimedia  
MySQL  
Oracle  
Perl  
PHP  
Practices  
Python  
Reviews  
Security  
Smartphone Development  
Style-Sheets  
Web Services  
XML  
Zend  
Zope  
Mobile Linux  
App Generation ROI  
IBM® developerWorks  
Forums Sitemap  
E-Commerce Hosting  
Linux Web Hosting  
Managed Hosting  
Small Business Hosting  
VPS Hosting  
Weekly Newsletter

 
Developer Updates  
Free Website Content 
 RSS  Articles
 RSS  Forums
 RSS  All Feeds
Write For Us Get Paid  
Request Media Kit
Contact Us  
Site Map  
Privacy Policy  
Support  
 USERNAME
 
 PASSWORD
 
 
  >>> SIGN UP!  
  Lost Password? 
PHP

Writing Self-Documenting PHP Code
By: Harish Kamath, (c) Melonfire
  • Search For More Articles!
  • Disclaimer
  • Author Terms
  • Rating: starstarstarstarstar / 14
    2002-04-15


    Table of Contents:
  • Writing Self-Documenting PHP Code
  • Speaking In Tongues
  • Drilling Deeper
  • I, Robot
  • Tonight's Menu
  • Different Strokes
  • Closing Time

  • Rate this Article: Poor Best 
      ADD THIS ARTICLE TO:
      error-file:tidyout.log Del.ici.ous error-file:tidyout.log Digg
      error-file:tidyout.log Blink error-file:tidyout.log Simpy
      error-file:tidyout.log Google error-file:tidyout.log Spurl
      error-file:tidyout.log Y! MyWeb error-file:tidyout.log Furl
    Email Me Similar Content When Posted
    Add Developer Shed Article Feed To Your Site
    Email Article To Friend
    Print Version Of Article
    PDF Version Of Article

     
     
    ADVERTISEMENT


    Writing Self-Documenting PHP Code - Different Strokes
    ( Page 6 of 7 )

    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
     

       

    PHP ARTICLES

    - Building Dynamic Queries with Chainable Meth...
    - PHP Encryption and Decryption Methods
    - Building a MySQL Abstraction Class with Meth...
    - Completing a Sample String Processor with Me...
    - Mastering WHILE Loops for PHP and MySQL
    - Method Chaining: Adding More Methods to the ...
    - Method Chaining in PHP 5
    - The Role of Interfaces in Applying the Depen...
    - Dependency Injection: Using a Setter Method ...
    - Using a Model Class with the Dependency Inje...
    - Injecting Objects Using Setter Methods with ...
    - Injecting Objects by Constructor with the De...
    - The Dependency Injection Design Pattern in P...
    - Performing Inferential Statistical Analysis ...
    - Performing Descriptive Statistical Analysis ...





    © 2003-2009 by Developer Shed. All rights reserved. DS Cluster 6 Hosted by Hostway
    Stay green...Green IT