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

From OpenEMR Project Wiki
m (1 revision: one)
 
 
(41 intermediate revisions by 4 users not shown)
Line 3: Line 3:


==What is a 'DocBlock'?==
==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 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 <code>/**</code> and each line of the body begins with a space-asterisk <code> *</code> and the characters <code> */</code> 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 <code> @package </code> tag. Ordinarily there would be an element-level DocBlock next following the page-level DocBlock.
===Short DocBlock===
===DocBlock Example===
A basic DocBlock looks like:
A basic DocBlock looks like:
<pre>
<pre>
/**
/**
  * Short Description
  * Summary which must end with period or two line breaks.
*
* Optional longer description or discussion that may contain
* inline tags and some html markup.  See the sections below for
* more details on the possible tags and markup.  Separated by
* blank lines, this is used in page-level DocBlocks and in
* element-level DockBlocks when the element merits further discussion.
* Section may contain markdown
*
* @since version number 
* @param <type> <name> <description>
* @return <type> (What is being returned)
*/
</pre>
Example:
<pre>
/**
* Test for uppercase.
  *  
  *  
  * @since         version number
  * @since version 0.2 
  * @param         variable for a function and what it takes as input
  * @param string $my_word text to be tested
  * @return        what it returns
* @return bool false if not uppercase
*/
function is_caps($my_word)
{
  return ($my_word === strtoupper($my_word));
}
</pre>
 
===Examples for OpenEMR===
======File-Level DocBlock======
Every file in the OpenEMR codebase should have a file-level DocBlock that contains basic information. Here's an example:
<pre>
/**
* Therapy group data template.
*
* @package  OpenEMR
* @link      http://www.open-emr.org
* @author    Rod Roark <rod@sunsetsystems.com>
* @author    Brady Miller <brady.g.miller@gmail.com>
* @author    Robert Down <robertdown@live.com>
* @copyright Copyright (c) 2016 Rod Roark <rod@sunsetsystems.com>
* @copyright Copyright (c) 2016 Brady Miller <brady.g.miller@gmail.com>
* @copyright Copyright (c) 2017 Robert Down <robertdown@live.com>
  * @license  https://github.com/openemr/openemr/blob/master/LICENSE GNU General Public License 3
  */
  */
</pre>
</pre>
===Long DocBlock===
 
A longer example look like:
======Element-Level DocBlock======
An element-level DockBlock should precede at least each function and each class in your code.
<pre>
<pre>
/**
/**
  * Short desc
  * Check if a Sql row exists. (with two values)
  *
  *
  * Long description first sentence starts here
  * This function will check if a selected sql row exists that contains two
* and continues on this line for a while
  * known values.
* finally concluding here at the end of
  * this paragraph
  *
  *
  * The blank line above denotes a paragraph break
  * @param  string  $tblname  Sql Table Name
  *  
* @param  string  $colname  Sql Column Name 1
* @param  string  $value    Sql value 1
* @param  string  $colname2 Sql Column Name 2
* @param  string  $value2  Sql value 2
* @return boolean          returns true if the sql row does exist
*/
function tableHasRow2D($tblname, $colname, $value, $colname2, $value2) {
    $row = sqlQuery("SELECT COUNT(*) AS count FROM $tblname WHERE " . "$colname
          LIKE '$value' AND $colname2 LIKE '$value2'");
    return $row['count'] ? true : false;
}
</pre>
 
===Most Available Tags===
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>
* @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
</pre>
 
======Element Level DocBlock:======
PhpDocumentor is capable of automatically documenting these elements: ''include'' statements, ''define'' statements, ''functions'', ''procedural pages'', ''classes'', ''class variables'', and ''class methods''.  The element level DocBlock is placed immediately above the element.
<p>
For the @param and @return tags, the datatype should be a valid PHP type (int, string, bool, etc), a class name for the type of object returned, or simply "mixed". If you want to explicitly show multiple possible return types, list them pipe-delimited without spaces (e.g. "@return int|string"). If a class name is used as the datatype in the @return tag, PhpDocumentor will automatically create a link to that class's documentation. In addition, if a function returns multiple possible values, separate them using the | character, and PhpDocumentor will parse out any class names in the return value. PhpDocumentor will display the optional description unmodified.
</p>
<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>
  * @since        version number
* @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
</pre>
 
======In-line DocBlock Tags======
Inline tags display in the documentation text flow where they appear. My guess is the <code> {@inheritdoc}</code> 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.
<pre>
/**
* 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
{
}
</pre>
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 &lt;pre&gt; notes... &lt;/pre&gt; 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.
<p>
You can use the following html markup tags: &lt;b&gt;  &lt;i&gt;  &lt;pre&gt;  &lt;code&gt;  &lt;var&gt;  &lt;ul&gt;  &lt;ol&gt;  &lt;li&gt; Be sure to use the corresponding closing tags as well.
</p>
<pre>
/**
* Base class for all output converters.
*
* The Converter marks the final stage in phpDocumentor.  phpDocumentor works
* in this order:
*
* &lt;pre&gt;Parsing =&gt; Intermediate Parsing organization =&gt; Conversion to output&lt;/pre&gt;
*
* 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:
* &lt;ul&gt;
*  &lt;li&gt;{@link HTMLframesConverter}&lt;/li&gt;
*  &lt;li&gt;{@link HTMLSmartyConverter}&lt;/li&gt;
*  &lt;li&gt;{@link PDFdefaultConverter}&lt;/li&gt;
*  &lt;li&gt;{@link CHMdefaultConverter}&lt;/li&gt;
*  &lt;li&gt;{@link CSVdia2codeConverter}&lt;/li&gt;
*  &lt;li&gt;{@link XMLDocBookConverter}&lt;/li&gt;
* &lt;/ul&gt;
* {@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 &lt;notaddress@nothere.nte&gt;
* @since 1.0rc1
* @version $Id: Converter.inc 291278 2009-11-24 17:43:20Z ashnazg $
*/     
</pre>
</pre>
===All Available Tags===
 
Here is a list of all tags available:
======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 <tt> /**#@+ </tt> the required six characters to indicate a template, one or more <tt> @tagname  value </tt> being the body, and the finishing characters <tt> */ </tt>. DocBlock templates are applied to all document-able elements until the ending template marker: <tt> /**#@-*/ </tt> is seen.
<p>
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 &quot;Two words&quot; included in the documentation for var $_var8. The template will not apply to var $publicvar.
</p>
<pre>
<pre>
* @abstract
class Bob
* @access      public or private
{
* @author      author name <author@email>
  // beginning of docblock template area
* @copyright    name date
  /**#@+
* @deprecated  description
  * @access private
  * @deprec      alias for deprecated
  * @var string
* @example      /path/to/example
  */
  * @exception    Javadoc-compatible, use as needed
  var $_var1 = 'hello';
* @global      type $globalvarname
  var $_var2 = 'my';
  or
  var $_var3 = 'name';
* @global      type description of global variable usage in a function
  var $_var4 = 'is';
* @ignore
  var $_var5 = 'Bob';
* @internal    private information for advanced developers only
  var $_var6 = 'and';
* @param        type [$varname] description
  var $_var7 = 'I';
* @return      type description
  /**
* @link        URL
  * Two words
* @name         procpagealias
  */
  or
  var $_var8 = 'like strings';
* @name        $globalvaralias
  /**#@-*/
* @magic        phpdoc.de compatibility
  var $publicvar = 'Lookee me!';
* @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
</pre>
</pre>


==Where to Use a DocBlock==
==Where to Use a DocBlock==
* All Files should have at least:
* All Files should begin with a page-level DocBlock with at least:
:* @package OpenEMR
:* @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
* Classes - For classes you want to use at least an @author tag
* Functions - For functions you want to use a short description
 
* Functions - For functions you want to use:
:* Use a @param tag for each field your function accepts
:* Use a @param tag for each field your function accepts
:* Use a @return tag to explain the data to be returned
:* Use a @return tag to explain the data to be returned
==Documentation in Your Development Repository==
The main 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 api documentation generated by PhpDocumentor and similar programs is an html web page and is created in a specified directory.  You point your web browser to that directory and the index.html page will have the links to your documentation.  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.
:* [http://pear.php.net/package/PhpDocumentor PhpDocumentor] superceded by v2, but my choice anyway <br />
:* [http://www.phpdoc.org/ phpDocumentor2]  (requires php-5.3 minimum, but still alpha release as of 6/25/2012)
:* [http://peej.github.com/phpdoctor PHPDoctor] download and unpack in your working directory
:* [http://apigen.org/ ApiGen] uses Nette framework, create API documentation from PHP source (php-5.3 min)
:* [http://www.stack.nl/~dimitri/doxygen/index.html doxygen] (DockBlock capability assumed as a subset of JavaDoc)
The command to create documentation with PhpDocumentor is:
<pre>
phpdoc -o HTML:frames:earthli -f sample1.php -t docs 
</pre>
and the command line options are seen with
<pre>
phpdoc -h
</pre>
The other programs are similar, so see the documentation for whichever program you choose.
<p>
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, so your generated documentation will not be part of the git commit process, but still available for your reference.
</p>
<p>
The various tags may not be recognized by all programs and html markup capability may not be consistent.  See [http://wiki.netbeans.org/DocumentingPhpCode NetBeans wiki] for some discussion on using the different programs.
</p>


==Inline Documentation==
==Inline Documentation==
Line 81: Line 274:
For, foreach, while and if statements all can get quite large and might need a little note above them.
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.
If you think you have a statement like this that needs a note, please make sure to do so.
== Update "Live" Wiki Documents ==
There are several "live" wiki documents that should get updated with the codebase:
1. New Database Tables:
:[[OpenEMR_System_Architecture#Database|OpenEMR System Architecture#Database]]
2. New Options (ie. Globals):
:[[Administration_Globals|Administration Globals]]
3. New User Specific Options:
:[[User_Settings|User Settings]]
4. New Lists:
:[[Administration_Lists|Administration Lists]]
5. New ACOs:
:[[Adding_and_Removing_User_Permissions|Adding and Removing User Permissions]]


==External Links==
==External Links==
* http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_elements.pkg.html
* 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
* http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_phpDocumentor.howto.pkg.html#basics.starting
[[Category:Developer Guide]]

Latest revision as of 19:10, 22 July 2017

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.

DocBlock Example

A basic DocBlock looks like:

/**
 * Summary which must end with period or two line breaks.
 *
 * Optional longer description or discussion that may contain 
 * inline tags and some html markup.  See the sections below for 
 * more details on the possible tags and markup.  Separated by 
 * blank lines, this is used in page-level DocBlocks and in 
 * element-level DockBlocks when the element merits further discussion.
 * Section may contain markdown
 * 
 * @since version number  
 * @param <type> <name> <description>
 * @return <type> (What is being returned)
 */

Example:

/**
 * Test for uppercase.
 * 
 * @since version 0.2  
 * @param string $my_word text to be tested
 * @return bool false if not uppercase
 */
function is_caps($my_word) 
{
  return ($my_word === strtoupper($my_word));
}

Examples for OpenEMR

File-Level DocBlock

Every file in the OpenEMR codebase should have a file-level DocBlock that contains basic information. Here's an example:

/**
 * Therapy group data template.
 *
 * @package   OpenEMR
 * @link      http://www.open-emr.org
 * @author    Rod Roark <rod@sunsetsystems.com>
 * @author    Brady Miller <brady.g.miller@gmail.com>
 * @author    Robert Down <robertdown@live.com>
 * @copyright Copyright (c) 2016 Rod Roark <rod@sunsetsystems.com>
 * @copyright Copyright (c) 2016 Brady Miller <brady.g.miller@gmail.com>
 * @copyright Copyright (c) 2017 Robert Down <robertdown@live.com>
 * @license   https://github.com/openemr/openemr/blob/master/LICENSE GNU General Public License 3
 */
Element-Level DocBlock

An element-level DockBlock should precede at least each function and each class in your code.

/**
 * Check if a Sql row exists. (with two values)
 *
 * This function will check if a selected sql row exists that contains two
 * known values.
 *
 * @param  string  $tblname  Sql Table Name
 * @param  string  $colname  Sql Column Name 1
 * @param  string  $value    Sql value 1
 * @param  string  $colname2 Sql Column Name 2
 * @param  string  $value2   Sql value 2
 * @return boolean           returns true if the sql row does exist
 */
function tableHasRow2D($tblname, $colname, $value, $colname2, $value2) { 
    $row = sqlQuery("SELECT COUNT(*) AS count FROM $tblname WHERE " . "$colname 
           LIKE '$value' AND $colname2 LIKE '$value2'"); 
    return $row['count'] ? true : false; 
} 

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 these elements: include statements, define statements, functions, procedural pages, classes, class variables, and class methods. The element level DocBlock is placed immediately above the element.

For the @param and @return tags, the datatype should be a valid PHP type (int, string, bool, etc), a class name for the type of object returned, or simply "mixed". If you want to explicitly show multiple possible return types, list them pipe-delimited without spaces (e.g. "@return int|string"). If a class name is used as the datatype in the @return tag, PhpDocumentor will automatically create a link to that class's documentation. In addition, if a function returns multiple possible values, separate them using the | character, and PhpDocumentor will parse out any class names in the return value. PhpDocumentor will display the optional description unmodified.

 * @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
  • Classes - For classes you want to use at least an @author tag
  • Functions - For functions you want to use:
  • 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 main 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 api documentation generated by PhpDocumentor and similar programs is an html web page and is created in a specified directory. You point your web browser to that directory and the index.html page will have the links to your documentation. 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.

  • phpDocumentor2 (requires php-5.3 minimum, but still alpha release as of 6/25/2012)
  • 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 as a subset of JavaDoc)

The command to create documentation with PhpDocumentor is:

 phpdoc -o HTML:frames:earthli -f sample1.php -t docs  

and the command line options are seen with

 
 phpdoc -h 

The other programs are similar, so see the documentation for whichever program you choose.

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, so your generated documentation will not be part of the git commit process, but still available for your reference.

The various tags may not be recognized by all programs and html markup capability may not be consistent. See NetBeans wiki for some discussion on using the different programs.

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.

Update "Live" Wiki Documents

There are several "live" wiki documents that should get updated with the codebase:

1. New Database Tables:

OpenEMR System Architecture#Database

2. New Options (ie. Globals):

Administration Globals

3. New User Specific Options:

User Settings

4. New Lists:

Administration Lists

5. New ACOs:

Adding and Removing User Permissions

External Links