Latest revision as of 19:12, 2 April 2009

Introduction

Geeklog's source code is documented using phpDocumentor. The syntax is similar to that used by JDoc or Doxygen but has a few special constructs and conventions specific to PHP source code.

The current documentation can be found at http://project.geeklog.net/src/, updated from the current development version every night.

Documenting functions

Every function should have a phpdoc header according to this template:

/**
* One-line description of the function
*
* Optional longer, multi-line description
* with further details.
*
* @param  type  $par1  short description of parameter
* @param  type  $par2  short description of parameter
* @return type         short description of return value
*
*/
function FOO_bar($par1, $par2)

The 'type' of parameter and return values should reflect the data type, e.g. string, int, boolean, array. Use mixed in case the parameter or return value can have more than one type. References should use ref.

Note: Use int instead of 'integer' and boolean instead of 'bool'.

Use other tags, e.g. @see, @deprecated, etc. where appropriate.

Packages

(To be defined. We need a concept first.)

Plugins

For now, each plugin is its own package with public_html and admin as subpackages for the files in public_html and public_html/admin/plugins, respectively.

For example:

/**
* Display poll results and past polls
*
* @package Polls
* @subpackage public_html
*/

Tips

@author

The @author tag will consider anything between angle brackets to be an email address and automatically translates it into a mailto: link. If you'd rather not have your email sitting there for any spambot to collect and switch to an obfuscated format, be sure to remove the angle brackets. Otherwise, phpDocumentor will create broken links from that "address".

Wrong:
@author John Doe, <john DOT doe AT example DOT com>

Better:
@author John Doe, john DOT doe AT example DOT com

Links

• phpDocumentor manual
• Commented Geeklog source code