How to document your source code

General

You can see the current LimeSurvey source code documentation on http://api.limesurvey.org

This documentation is created on an hourly base by phpDocumentor.

The LimeSurvey project is using phpDocumentor to easily create source code documentation. phpDocumentor is an easy way to markup your source-code with specially formatted comments and let the software phpDocumentor afterwards extract this information about your classes/methods/function/variable and show it as a nice documentation.

phpDocumentor Quick-Start

However, the work to create the comments comes first. So here is how it works:

1. Go to phpdoc2cheatsheet.com and download the PHPDoc cheatsheet in your preferred format.
2. Print it out as a poster and pin it to your wall above your PC monitor.
3. Since the knowledge is not magically transferred from the cheatsheet to your brain, here is the short form instruction to give you a 'head' start (:biggrin:):

A PHPDoc comment always starts with /** (slash and two asterisks), every following line inside the comment has to start with an * (asterisk), and it is close with */ (single asterisk and slash), like this

/**
 * Global variable declaration docBlock
 * @global integer $GLOBALS['_myvar']
 * @name $_myvar
 */

• A PHPDoc comment has always to precede the code it is made for (except for the File comment, which documents the file itself and cannot be placed outside the PHP tags)
• Inside the comment you can use the phpDocumentor tags as described on the cheat sheet. A typical PHPDoc comment for a function would look like this:

/**
 * CleanLanguagesFromSurvey() removes any languages from survey tables that are not in the passed list
 * Please use carefully as the data is permanently deleted
 *
 * @param string $sid - the currently selected survey
 * @param string $availlangs - space separated list of additional languages in survey (IANA code)
 * @global string $connect- the database connection object
 * @return bool - always returns true
 *
 * @since 1.5.0.1642 (2007-01-02)
 * @author David Olivier
 */

function CleanLanguagesFromSurvey($sid, $availlangs)
{
   global $connect;
   $sid=sanitize_int($sid);
   $baselang = GetBaseLanguageFromSurveyID($sid);
       [....]

The above example code block demonstrates nicely how it is done:

• First thing in the comment is a natural description of the functions purpose. Be as descriptive as possible. You can use several lines of description.
• The @param tags are describing the parameters of the function in the form '@param datatype variablename  description'
• @global describes any global variable used in the function - same form as the @param tag
• @return describes the value the function returns
• @since is an optional parameter - it documents when a function was first added to the code - please name at least the subversion build number
• @author is pretty self-explaining

That's it. The examples on the cheat sheet for the File, Class, and Variable documentation are self-explaining.

Errors on documentation generation

When phpDocumentor is creating the documentation it might stumble over errors in the source code documentation you wrote. All errors generated by the last documentation run can be seen on http://api.limesurvey.org/errors.html .

Be sure to visit this page regularly to check if your documentation is parsing right.

Still if you have comments or questions do not hesitate to contact me or change this document accordingly.