View source for 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 [http://www.phpdoc.org/ 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:
#Go to [http://phpdoc2cheatsheet.com/ phpdoc2cheatsheet.com] and download the PHPDoc cheatsheet in your preferred format.
#Print it out as a poster and pin it to your wall above your PC monitor.
#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

<syntaxhighlight lang="php">

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

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

<syntaxhighlight lang="php">

/**
 * 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);
       [....]
</syntaxhighlight>

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.

[[Category:Development]]

==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 [[UserPage c_schmitz|me]] or change this document accordingly.