Writing Self-Documenting PHP Code - Tonight's Menu (
Page 5 of 7 )
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:
/ 14 
