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.
