PHPDoc Howto

This document outlines how you can generate the phpdoc-based help files.

The neccessary PHPDoc configuration files are located in /fs-midcom/support of the MidCOM CVS repository. There are two files, one creating only a simple, HTML-based help (which is reasonably fast), and another one creating several HTML-Variants, the source for a CHM file and a PDF (quite time-intensive).

These files will write their output to /tmp/midcom-docs/, you have to collect it there. This directory should be already there.

Then, when everything is in place, run "phpdoc -c config_name" within the support directory, and you should be fine.

The current configuration will skip all files in directories called "*/style/*", "*/config/*", "*/locale/*" and "*/documentation/*" thus ending up with the actual code in the system. Parsed will be everything in the lib directory of the CVS checkout.

Everything which is not yet documented, goes into the package "undocumented" for a start. This is not usable for makedist too.

How to document

A good end-user documentation is of top-most importance, as we have seen more then once with the incomplete documentation of the Midgard Core. Therefore I strongly urge all contributors to take their time documenting the code they write while they write it.

Yes, I know that this takes time (I use about a third of my development time for documentation), but in the end this will save you much time answering all the silly questions of the casual end-users/newcomers.

The following guidelines are from my personal experience, and they are open for discussion:

Class documentation

A good class introduction for example consists out of these elements in roughly this order:

Introduction what the class does in general, one, two paragraphs at most
More detailed textual description about what it does
Examples / Short HowTo's
Warnings / Notes about common Pitfalls
Copyright stuff for 3rd Party applications (like HTMLArea for the Datamanager)

Global- and member-variable documentaion

The docs for variables can usually be rather short, as most of them will be self-explenatory. When using simple base types for things like "Form field name prefix" can be enough.

Only complex types, like special error strings with formatting convetions or multi-level accocitive arrays as the datamanager schema database, call for a more verbose explaination, that could even be combined with an example how it can look like.

Function documentation

The documentation of the member functions of a class is almost as important, as the class documentation itself. You should hold yourself to the same general schema as with class documentations, omitting those parts, that are obviously not needed.

You absolutely always need to document all parameters using the @param documentation tag with both object type (use mixed, MidgardObject or the base class of a hierarchy as generic types where appropriate). It is imporant to use the names of other documented classes where appropriate, as this will by hyperlinked automatically.

As mandatory is the documentation of the return value using @return specifying both type and meaning. Often enough, a short note like @return bool Indicating success can be enough to clarify a functions usage.

Note, that null is not a type in itself, but a value for any existing type regarding documentation; a function that returns an integer or null on failure is still of type int.

Documentation style

Try to keep the style of the documentation as uniformly as possible. For example, I have started to use italics to mark important points in favor of bold typefaces; small headlines in the midst of a text block consist of a bold paragraph (phpdoc does not support headings).

Please get a look how things were done previously and try to stay in the same layout. The more you do this, the less the documentation needs to be typographically maintained in the long run. Thank you! ;-)

If in doubt...

If you are in doubt how to document an element, take a look into the alredy documented part of MidCOM and use the style of these files as a guideline for your own documentation.

Dock Block Examples

Package names

Use the @package directive to group the documentation along the following guidelines:

Everything in the core which is not directly accociated with a component goes under midcom.
Everything in a component, including core components, goes into a package named after their component, for example midcom.helper.datamanager or de.linkm.taviewer.

File Introduction

For each file, prepend something like this:

/**
 * @package midcom
 * @author The Midgard Project, http://www.midgard-project.org 
 * @version $Id: application.php,v 1.8 2004/11/10 12:13:42 torben Exp $
 * @copyright The Midgard Project, http://www.midgard-project.org
 * @license http://www.gnu.org/licenses/lgpl.html GNU Lesser General Public License
 */

Class Introductions

Write verbose documentations about what the class does. In addition, you will have to add another @package tag within the class, PHPdoc doesn't get this on itself:

/**
 * Main controlling instance of the MidCOM Framework
 * 
 * [...]
 *
 * @package midcom
 */

Visibility specification on classes, variables and functions

Add a @access private to any class member that should not be used from outside. Current default settings will add them to the documentations for now, but these docblocks are definitly meant for developers, not for end users.

Alternativly, you can use @access protected for all members that can be used in inherited classes.

The default visibility is public, so you don't need to specify this in that case explicitly.

Common Pitfalls with < and >

Even in blocks surrounded by <pre> tag's PHPDoc appearantly does *not* replace the <> tags automatically with the corresponding HTML Entities. This means, that you unfortunalety have to use > and < respectivly in these cases.

Output notes

PDF

The PDF output takes quite a while, so you should be prepared to bring some time (and some 200 MB of system memory) with you.

Compiled HTML Help (CHM)

phpdoc does not bring a CHM-converter, but the generated source can be converted using the Microsoft HTML Help Workshop, which is free for download.

Example

A more or less (probably more less) current demo can be found here.