How to Document Your Code Properly

We're glad you're interested in developing for OpenEMR, but before you start adding, it's important that you remember to document your code. What follows, is a basic guide for how to document what you are doing.

What is a 'DocBlock'?

A DocBlock is format that evolved from C++. It is a clean, standards compliant way of documenting your code, which allows for easy reading and parsing.

Short DocBlock

A basic DocBlock looks like:

/**
 * Short Description
 * 
 * @since         version number
 * @param         variable for a function and what it takes as input
 * @return        what it returns
 */

Long DocBlock

A longer example look like:

/**
 * Short desc
 *
 * Long description first sentence starts here
 * and continues on this line for a while
 * finally concluding here at the end of
 * this paragraph
 *
 * The blank line above denotes a paragraph break
 * 
 * @author       author name <author@email>
 * @since        version number
 */

All Available Tags

Here is a list of all tags available:

* @abstract
 * @access       public or private
 * @author       author name <author@email>
 * @copyright    name date
 * @deprecated   description
 * @deprec       alias for deprecated
 * @example      /path/to/example
 * @exception    Javadoc-compatible, use as needed
 * @global       type $globalvarname 
   or
 * @global       type description of global variable usage in a function
 * @ignore
 * @internal     private information for advanced developers only
 * @param        type [$varname] description
 * @return       type description
 * @link         URL
 * @name         procpagealias
   or
 * @name         $globalvaralias
 * @magic        phpdoc.de compatibility
 * @package      package name
 * @see          name of another element that can be documented,
 *                produces a link to it in the documentation
 * @since        a version or a date
 * @static
 * @staticvar    type description of static variable usage in a function
 * @subpackage    sub package name, groupings inside of a project
 * @throws       Javadoc-compatible, use as needed
 * @todo         phpdoc.de compatibility
 * @var        type    a data type for a class variable
 * @version    version

Where to Use a DocBlock

• All Files should have at least:

• @package OpenEMR
• @license GNU/GPL (the full license will be listed in license.txt and should no longer be included with every file)

• Classes - For classes you want to use a long description with at least an @author and @since tag
• Functions - For functions you want to use a short description

• Use a @param tag for each field your function accepts
• Use a @return tag to explain the data to be returned

Inline Documentation

Obviously classes and functions aren't the only places where things are going that need some documentation. For, foreach, while and if statements all can get quite large and might need a little note above them. If you think you have a statement like this that needs a note, please make sure to do so.

External Links

• http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_elements.pkg.html
• http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_phpDocumentor.howto.pkg.html#basics.starting