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