Source Code Documentation

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
*/