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

Tonight's Menu - 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, what you saw on the previous page was just an example. Let's apply PHPDoc to an actual PHP class, one created by me a while back and pulled out of our archives for just this purpose, and see what happens.


<?php /** * A Menu object which exposes certain generic methods. * * These methods will have nothing to do with the visual presentation of * the menu tree; rather, they provide a simple API to various menu * relationships, and can be used by client- or server-side scripts * which are more closely connected to the presentation layer. * * @author Melonfire <melonfire@mail.com> * @version 1.0 * @since 1.0 * @access public * @copyright Melonfire */ class Menu { /** * The hostname of the server hosting the database. * * @var string * @access public * @since 1.0 * @see set_database_parameters() */ var $hostname; /** * The username required for logging in to the database server. * * @var string * @access public * @since 1.0 * @see set_database_parameters() */ var $user; /** * The password required for logging in to the database server. * * @var string * @access public * @since 1.0 * @see set_database_parameters() */ var $password; /** * The name of the database containing the required tables. * * @var string * @access public * @since 1.0 * @see set_database_parameters() */ var $db; /** * The name of the table containing the menu information. * * @var string * @access public * @since 1.0 * @see set_database_parameters() */ var $table; /** * The constructor for the Menu class sets some default values for the database parameters * * @access public * @since 1.0 * */ function Menu() { $this->set_database_parameters("localhost", "me", "bs49h5634", "apps","menu"); } /** * This function is used to set the database parameters as specified by the user. * * @param string $hostname The host name of the database server * @param string $user The username for accessing the database server * @param string $password The password for accessing the database server * @param string $db The name of the database to be accessed * @param string $table The name of the table that stores the menu * @access public * @since 1.0 * @see query() * */ function set_database_parameters($hostname, $user, $password, $db, $table) { $this->hostname = $hostname; $this->user = $user; $this->password = $password; $this->db = $db; $this->table = $table; } /** * This is a generic function to execute a query that is passed as a parameter * * @param string $query The query to be executed * @return mixed $ret * @access public * @since 1.0 * */ function query($query) { // connect $connection = mysql_connect($this->hostname, $this->user, $this->password) or die ("Cannot connect to database"); // run query $ret = mysql_db_query($this->db, $query, $connection) or die ("Error in query: $query"); // return result identifier return $ret; } /** * This function returns the id of the parent of a node * * @param int $id The id of the node who parent has to be returned by function * @return int $id * @access public * @since 1.0 * */ function get_parent($id) { $query = "SELECT parent FROM $this->table WHERE id = '$id'"; $result = $this->query($query); $row = mysql_fetch_row($result); return $row[0]; } } ?>
Here's the PHP script which hooks this class file up to PHPDoc and actually generates some documentation:

<html> <head> </head> <body> <?php // where are the PHPDoc files? // alter this as per your setup define("PHPDOC_INCLUDE_DIR", "/usr/local/apache/htdocs/phpdoc/"); // system linebreak sequence // alter this as per your setup define("PHPDOC_LINEBREAK", "\r\n"); // include PHPDoc files include("prepend.php"); // instantiate a PHPDoc object $doc = new Phpdoc; // set application name $doc->setApplication("Menu"); // source file location // alter this as per your setup $doc->setSourceDirectory("/usr/local/apache/htdocs/phpdoc/Menu/"); // destination directory for generated docs // alter this as per your setup $doc->setTarget("/usr/local/apache/htdocs/phpdoc/Menu/docs/"); // template location // alter this as per your setup $doc->setTemplateDirectory("/usr/local/apache/htdocs/phpdoc/renderer/htm l/te mplates/"); // source file suffixes $doc->setSourceFileSuffix( array ("php", "inc") ); // parse $doc->parse(); // and render $doc->render(); ?> </body> </html>
And here's what it all looks like:



 
 
>>> 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: