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

Speaking In Tongues - 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.

  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


PHPDoc is based on Javadoc, the trailblazing documentation standard for Java application code. Javadoc began as in-house effort at Sun Microsystems to ensure consistency in code documentation; it rapidly turned into an unofficial standard used by millions of Java programmers worldwide.

According the Javadoc site (http://java.sun.com/j2se/javadoc/), "...the Javadoc tool parses the declarations and documentation comments in a set of Java source files and produces a corresponding set of HTML pages describing (by default) the public and protected classes, nested classes (but not anonymous inner classes), interfaces, constructors, methods, and fields..."

Ouch! Why can't these guys speak plain English?!

Let me translate: Javadoc is a tool that reads and parses the comments within the source code of a Java package, and automatically converts these comments into human-readable API documentation. Obviously, the process is not completely automatic - the developer still needs to follow some basic rules while creating the comments - but using Javadoc to generate API documentation is still faster than doing it manually.

PHPDoc is similar to Javadoc. It, too, uses comments (in the same style employed by Javadoc) placed within a class' source code to automatically and transparently create API documentation that can be delivered to a customer together with the source code. It doesn't do everything Javadoc can do, primarily because PHP is a far simpler language than Java and the additional complexity is not really necessary; however, as you will see, it packs more than enough power for most purposes.

Before I get into the nitty-gritty of using PHPDoc, I'm going to quickly review the basics of the comment style used, so that you have a better understanding of the concept and how it works. Flip the page, and let's get started. {mospagebreak title=A Quick Snack} PHPDoc requires that the comments placed by a developer within his or her source code conform to a particular format. Assuming this format, PHPDoc can parse these comments and use them to create an API document.

In order to demonstrate this, let's consider the following simple PHP class, which claims to automatically make a sandwich for you. This class has been marked up with PHPDoc-compatible comments.

<?php /** * Automatically creates a sandwich customized to your preferences * * @author Melonfire <melonfire@mail.com> * @version 2.0 * @since 1.3 * @access public * @copyright Melonfire * */ class SandwichMaker { /** * Bread type * * @var integer * @access public * @see setType() */ var $type; /** * Sandwich filling * * @var array * @access public * @see setFillings() */ var $fillings = array(); /** * Creates a sandwich with specified bread type and filling * * @return Boolean * @access public */ function makeSandwich() { // snip } /** * Sets bread type for sandwich * * @param integer $type bread type * @return Boolean * @access public * @see makeSandwich() * @see setFillings() */ function setType($type) { // snip } /** * Sets filling for sandwich * * @param array $fillings list of fillings * @return Boolean * @access public * @see makeSandwich() * @since 1.2 */ function setFillings($fillings) { // snip } } ?>
There are some fundamental rules you should be aware of when creating these comment blocks:

1. Every comment block must begin with a forward slash (/) followed by two asterisks (**).

2. Subsequent lines begin with an asterisk (*), which is indented to appear under the first asterisk of the opening line.

3. The end of the block is defined by an asterisk (*), followed by a forward slash (/).

Such comment blocks are usually present at both package and module level in Java. Since PHP does not group objects in this way, you don't usually have to worry about these (although you can, if your code is organized according to this convention).

Once you've got the initial comment block set up, PHPDoc lets you add some information to it. This information consists of a single-line description of the item, together with zero or more tags containing further information. The description and tags are separated by a single line containing a single asterisk (*).

Each Javadoc "tag" consists of the @symbol, a keyword and a value. For example, the tag

@author Melonfire <melonfire@mail.com>
when used in a class context, indicates that the class was created by Melonfire, while the tag

@version 2.0
indicates that the class is currently at version 2.0

There are three types of comment blocks you may use here:

1. Class comment block: This comment block provides a general overview of the class, its purpose, its authors and its version number. It typically appears right at the top of the class definition.

2. Variable comment block: This comment block is used to document class variables or properties; it provides information on the variable type, its raison d'etre, and references to other class variables that it is related to.

3. Method comment block: This comment block documents class methods, providing detailed information on method arguments, return values and public/private access.

Let's look at each of these in detail.

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

blog comments powered by Disqus
escort Bursa Bursa escort Antalya eskort


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