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.
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>
/ 14 
