Difference between revisions of "How to Document Your Code Properly"

From OpenEMR Project Wiki
m (2 revisions: How_to_Document_Your_Code_Properly)
Line 32: Line 32:
  */
  */
</pre>
</pre>
===All Available Tags===
===Most Available Tags===
Here is a list of all tags available:
Here is a partial list of tags available in PhpDocumentor.  See [http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_phpDocumentor.howto.pkg.html 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 <code> &lt;?php</code>. PhpDocumentor parses a DocBlock as a page-level DocBlock if it precedes another DocBlock or if it is the first DocBlock and contains the <code> @package </code> tag.
<pre>
<pre>
* @abstract
* @author      authorName <author@email>
  * @access       public or private
* @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
</pre>
======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.
<pre>
* @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>
  * @author      author name <author@email>
* @copyright    name date
  * @deprecated  notify users of elements that should not be used any longer
  * @deprecated  description
  * @example      /path/to/example description, your example for using your code
* @deprec      alias for deprecated
  * @global      refer to manual -- two usages of @global: definition and function usage.
  * @example      /path/to/example
  * @ignore       to prevent phpDocumentor from documenting an element, such as a duplicate element.
* @exception    Javadoc-compatible, use as needed
  * @since        version or date when element introduced (e.g. @since Version 21.1)
  * @global      type $globalvarname
 
  or
  * @link        URL, a complete url e.g. http://www.domain.ten/page
* @global       type description of global variable usage in a function
  * @see          element reference    create a link to element in the documentation
  * @ignore
  * @uses         element reference    ( e.g. @uses my_util_func() )
  * @internal    private information for advanced developers only
                  creates link to element documentation and a pseudo-link 'usedby' in the element documentation
* @param        type [$varname] description
 
  * @return      type description
  * @staticvar    type    description of static variable usage in a function
  * @link         URL
  * @var          type    a data type for a class variable
  * @name         procpagealias
 
  or
  ****** special case
  * @name        $globalvaralias
  * @access      public or private, if private, element will not be documented, default is public
  * @magic        phpdoc.de compatibility
  * @internal    should not be displayed in public documentation, private information for advanced developers only
  * @package      package name
</pre>
  * @see          name of another element that can be documented,
 
  *               produces a link to it in the documentation
======In-line DocBlock Tags======
  * @since        a version or a date
Inline tags display in the documentation text flow where they appear. My guess is the <code> {@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.
  * @static
<pre>
  * @staticvar    type description of static variable usage in a function
/**
  * @subpackage    sub package name, groupings inside of a project
* inline tags demonstration
  * @throws      Javadoc-compatible, use as needed
*
  * @todo        phpdoc.de compatibility
  * this function works heavily with {@link foo()} to rule the world. If I want
  * @var        type    a data type for a class variable
  * to use the characters "{@link" in a docblock, I just use "{@}link."  If
  * @version    version
  * I want the characters "{@*}" I use "{@}*}"
  *
  * @param string
  * @return string
  */
function bar($foo2)
{
    return $foo2;
}
</pre>
</pre>



Revision as of 15:53, 25 June 2012

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

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 function 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 "{@}*}"
 *
 * @param string
 * @return string
 */
function bar($foo2)
{
    return $foo2;
}

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