Source Code Documentation - Revision history

Dirk: Tip for @author

2009-04-02T19:12:39Z

Tip for @author

Dirk: Link to the phpDocumentor manual

2009-03-29T09:36:52Z

Link to the phpDocumentor manual

Dirk: Started documenting how to document the source code

2009-03-28T15:24:18Z

Started documenting how to document the source code

New page

= Introduction =

Geeklog's source code is documented using [http://phpdoc.org/ 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:

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

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

'''Note:''' Use <tt>int</tt> instead of 'integer' and <tt>boolean</tt> instead of 'bool'.

Use other tags, e.g. <code>@see</code>, <code>@deprecated</code>, etc. where appropriate.

= Packages =

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

== Plugins ==

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

For example:

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

[[Category:Development]]

@@ Line 50: / Line 50: @@
 */
 </pre>
 = Links =
 * [http://manual.phpdoc.org/HTMLframesConverter/default/ phpDocumentor manual]
 [[Category:Development]]