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

Drilling Deeper - 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
As you can see from the example on the previous page, a general overview of the class is provided in the comment block preceding the class definition.


<?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() { // snip } ?>
The first line within the comment block provides a brief, human-readable description of the class. It is followed by a blank line, and a series of tags.

Each of the tags in the comment block above provides information on some aspect of the class. Here's a brief list of what they represent:

@author - the name of the class author

@version - the current version number of the class

@since - historical information on the availability of this class

@access - whether this class is a private or public class

@copyright - the name of the copyright holder of the class

Most of these tags are optional; PHPDoc will either use default values if they are not present, or simply ignore their absence.

If a class has multiple authors, you may list them using multiple @author tags - remember to group them together so that the parser has no difficulty finding all of them.

If you would like to group your classes together, you can also use the

@package package-name
tag as a grouping key; PHPDoc will then use the package name to group all related classes together when creating the documentation.

Moving on, once the class has been documented, the next step is to document the class variables. Here's an example:

<?php /** * Bread type * * @var integer * @access public * @see setType() */ var $type; ?>
In addition to the tags described above, class variables can have two additional tags, both of which are fairly self-explanatory:

@var - the variable type

@see - references to other, related variables and methods

Finally, all that's left is to document the class methods. Here's a quick example,

<?php /** * Sets bread type for sandwich * * @param integer $type bread type * @return Boolean * @access public * @see makeSandwich() * @see setFillings() */ function setType($type) { // snip } ?>
Class methods can use two additional tags, in addition to the ones previously described:

@return - a description of the return value from the method

@param - a description of the argument passed to the method, in the form


@param arg-type arg-name arg-description
Obviously, you should include as many @param tags as there are arguments to be passed to the method, and you should make it a point to list them in the order in which the method expects them.

It should be noted that the @see tag is particularly useful when it comes to documenting class methods - it provides an easy way to create connections between related methods. PHPDoc will automatically hyperlink the methods named in the @see tag to each other when it creates the documentation.

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