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. A DocBlock begins with the three character line /** and each line of the body begins with a space-asterisk * and the characters */ make the last line of the DocBlock. A DocBlock is placed immediately above the element being documented. A Page-level DocBlock is the first DocBlock and contains the @package tag. Ordinarily there would be an element-level DocBlock next following the page-level DocBlock.
Short DocBlock
A basic DocBlock looks like:
/** * Short Description * * @since version number * @param type argument for a function and what it takes as input * @return type what it returns */
Example:
/**
* test for uppercase
*
* @since version 0.2
* @param string text to be tested
* @return boolean if not obvious, false if not uppercase
*/
function is_caps($my_word)
{
return ($my_word === strtoupper($my_word));
}
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 * @param type argument for a function and what it takes as input * @return type what it returns */
Most Available Tags
Here is a partial list of tags available in PhpDocumentor. See PhpDocumentor Manual Listing them as Page- or Element-Level is not meant to restrict usage, but some tags are indeed intended for certain DocBlock levels.
Page Level Doc Block:
The page level DocBlock should appear at the top of the file, after the opening <?php. PhpDocumentor parses a DocBlock as a page-level DocBlock if it precedes another DocBlock or if it is the first DocBlock and contains the @package tag.
* @author authorName <author@email>
* @copyright authorName date
* @license URL name of license (e.g. http://opensource.org/licenses/gpl-license.php GNU General Public License, Version 3)
* @package packageName groups the class or elements in the file into a "package" in the documentation
****** optional tags
* @category categoryName organize groups of packages, if used include @package tag in DocBlock
* @subpackage singleWordName groupings inside of a package, @package tag must also be present
* @filesource The tag can only be used in a page-level DocBlock,
parses the file source of the current file, outputs syntax-highlighted source, creates link
* @version version
* @link URL, a complete url e.g. http://www.domain.ten/page
Element Level DocBlock:
PhpDocumentor is capable of automatically documenting include statements, define statements, functions, procedural pages, classes, class variables, and class methods. The element level DocBlock is placed immediately above the element.
* @package packageName only for classes at element level
****** usually required ******
* @param type [$varname] description (one for each function argument)
* @return type description
****** optional
* @author author name <author@email>
* @deprecated notify users of elements that should not be used any longer
* @example /path/to/example description, your example for using your code
* @global refer to manual -- two usages of @global: definition and function usage.
* @ignore to prevent phpDocumentor from documenting an element, such as a duplicate element.
* @since version or date when element introduced (e.g. @since Version 21.1)
* @link URL, a complete url e.g. http://www.domain.ten/page
* @see element reference create a link to element in the documentation
* @uses element reference ( e.g. @uses my_util_func() )
creates link to element documentation and a pseudo-link 'usedby' in the element documentation
* @staticvar type description of static variable usage in a function
* @var type a data type for a class variable
****** special case
* @access public or private, if private, element will not be documented, default is public
* @internal should not be displayed in public documentation, private information for advanced developers only
In-line DocBlock Tags
Inline tags display in the documentation text flow where they appear. My guess is the {@inheritdoc} is of the most interest, since it can simplify documentation of parent and child classes. PhpDocumentor will automatically inherit the @author tag, @version tag, and @copyright tag from a parent class. Reference the manual for more information.
/**
* inline tags demonstration
*
* This class generates bars using the main algorithm, which also
* works heavily with {@link foo()} to rule the world. If I want
* to use the characters "{@link" in a docblock, I just use "{@}link." If
* I want the characters "{@*}" I use "{@}*}"
*
* @author ahobbit
* @copyright middleearth.org XVII
* @version 1.2.3
*/
class bar
{
}
/**
* Makes chocolate bars
*
* There are two aspects to this class.
* {@inheritdoc } In addition, the foo class
* makes the bars chocolate
*/
class foo extends bar
{
}
The documentation for class foo will include the documentation from class bar.
HTML markup in DocBlocks
The next example illustrates the use of selected html markup tags to format documentation features. The <pre> notes... </pre> construct may the the most useful to separate some formatted text from the rest of your description. This is from PhpDocumentator Converter.inc. The @abstract tag is no longer used. You will also notice the @internal tag which allows some documentation to be seen only by certain people.
You can use the following html markup tags: <b> <i> <pre> <code> <var> <ul> <ol> <li> Be sure to use the corresponding closing tags as well.
/**
* Base class for all output converters.
*
* The Converter marks the final stage in phpDocumentor. phpDocumentor works
* in this order:
*
* <pre>Parsing => Intermediate Parsing organization => Conversion to output</pre>
*
* A Converter takes output from the {@link phpDocumentor_IntermediateParser} and
* converts it to output. With version 1.2, phpDocumentor includes a variety
* of output converters:
* <ul>
* <li>{@link HTMLframesConverter}</li>
* <li>{@link HTMLSmartyConverter}</li>
* <li>{@link PDFdefaultConverter}</li>
* <li>{@link CHMdefaultConverter}</li>
* <li>{@link CSVdia2codeConverter}</li>
* <li>{@link XMLDocBookConverter}</li>
* </ul>
* {@internal
* The converter takes output directly from {@link phpDocumentor_IntermediateParser}
* and using {@link walk()} or {@link walk_everything} (depending on the value of
* {@link $sort_absolutely_everything}) it "walks" over an array of phpDocumentor elements.}}
*
* @package Converters
* @abstract
* @author Greg Beaver <notaddress@nothere.nte>
* @since 1.0rc1
* @version $Id: Converter.inc 291278 2009-11-24 17:43:20Z ashnazg $
*/
DocBlock Templates
As the last example, I want to show the DocBlock template which can simplify documentation for a succession of similar code elements.
The format is /**#@+ the required six characters to indicate a template, one or more @tagname value being the body, and the finishing characters */ . DocBlock templates are applied to all document-able elements until the ending template marker: /**#@-*/ is seen.
The example from the tutorial shows the template below and all elements up to var $publicvar will be documented with the tags @access private and @var string, with "Two words" included in the documentation for var $_var8. The template will not apply to var $publicvar.
class Bob
{
// beginning of docblock template area
/**#@+
* @access private
* @var string
*/
var $_var1 = 'hello';
var $_var2 = 'my';
var $_var3 = 'name';
var $_var4 = 'is';
var $_var5 = 'Bob';
var $_var6 = 'and';
var $_var7 = 'I';
/**
* Two words
*/
var $_var8 = 'like strings';
/**#@-*/
var $publicvar = 'Lookee me!';
}
Where to Use a DocBlock
- All Files should begin with a page-level DocBlock with 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
Documentation in Your Development Repository
The API documentation will actually be produced in the main repository. However, you will benefit by having your own documentation capability in your git branch repository on your computer. The PhpDocumentor is available as a Pear package and there are other documentation programs as well. PhpDocumentor is the program of choice, but it does not handle namespaces or closures in PHP and will crash if it encounters these new features.
- PhpDocumentor superceded by v2, but my choice anyway
- phpDocumentor2 (requires php-5.3 minimum, but not quite ready for prime-time IMHO
- PHPDoctor download and unpack in your working directory
- ApiGen uses Nette framework, create API documentation from PHP source (php-5.3 min)
- doxygen (DockBlock capability assumed, not verified)
Each program, to my knowledge, has an output parameter which lets you store the documentation in the specified directory. In your git repository, I suggest including the documentation directory in the .gitignore file.
The various tags may not be recognized by all programs. See NetBeans wiki for some discussion on this topic.
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
