Dolphin 8: autogenerated documentation

This is a continuation of my previous post - Dolphin 8: new programming approaches, but with accent on proper code commenting. Proper code commenting allows to generate more structured, clean and easy to read programmers documentation.

We are using Doxygen to generate documentation from source code. This guide highlights useful Doxygen commands to use in PHP code comments to generate nice Dolphin programming documentation.

This is guideline for Dolphin developers, but it should be helpful for other developers who care about writing the proper comments in own code.

1. Files Header and Footer

Make sure that every file has the following header:

<?php defined('BX_DOL') or die('hack attempt');
/**
 * Copyright (c) BoonEx Pty Limited - http://www.boonex.com/
 * CC-BY License - http://creativecommons.org/licenses/by/3.0/
 *
 * @defgroup    DolphinCore Dolphin Core
 * @{
 */

/** @} */ 

2. Grouping the files

Use the following groups and subgroups in header of every file:

• for all files in /inc/ folder

    @defgroup    DolphinCore Dolphin Core
  

• for all files in /templates/[base|tmpl_uni] folder

    @defgroup    DolphinView Dolphin Core Representation classes
    @ingroup     DolphinCore  
  

for all files in root - / folder only

  @defgroup    DolphinEndUser Dolphin Core End User Pages 
  @ingroup     DolphinCore  

• for all files in /studio/ folder

    @defgroup    DolphinStudio Dolphin Studio
  

• for all files in /modules/ folder

    @defgroup    MyModule Full name of MyModule
    @ingroup     DolphinModules  
  

3. Lists

For lists use the following format:

My list:
- one
- two
- three

For multi indented list use the following format:

- first
	- a
	- b
- second
	- c
	- d

4. Code blocks

Code blocks must be enclosed in @code and @endcode tags.
For example:

@code
echo "Hello World!"; 
@endcode

5. Sections

/**
 * My class
 *
 * My class desc goes here.
 *
 * @section example Example of usage:
 * @code
 *      $o = new MyClass();
 * @endcode
 *
 * @section alerts Alerts:
 * myalert - with the following parameters
 * - $iObjectId - my content id
 * - $iSenderId - user who performed an action with my content
 *
 */
    

• @section alerts Alerts:
• @section acl Memberships/ACL:
• @section example Example of usage:

6. Line breaks

To make line break in documentation you need to insert double line break in the code.

For example, the following code:

My class code
It is used for some purpose.

My class codeIt is used for some purpose.

My class code

It is used for some purpose.

Also you can use @n to force new line anywhere.

7. Pages

This is ready documentation pages, so you can add page comment block somewhere in the code and documentation page will be generated.

There are some predefined documentation pages where you can add content. For example "Objects" documentations page consists of references to all "Objects".

This is an example on how to add content to "Objects" documentation page:

/** 
 * @page objects 
 * @section comments Comments
 * @ref BxDolCmts
 */

8. Functions commenting format

make sure that functions/class methods comments have the following format:

/**
 * Description is here.
 * @param mixed $mixedData function data to process
 * @param int $iDataType function data type
 * @return abra kadabra
 */
function sample ($mixedData, $iDataType) {
}

9. Classes commenting format

Class comment must have description of general class functionality and the following sections, if they have place

• Example of usage
• List of all membership/acl actions this class is using
• List of all alerts this class can raise

Refer to BxDolCmts class for examples.

10. One string comments

Make sure that one string comments for class properties, defines and global variables are formatted like this:

define('BX_DATA_INT', 3); ///< integer date type
define('BX_DATA_FLOAT', 4); ///< float date type
define('BX_DATA_HTML', 5); ///< HTML date type

If one line comments are written using this format - then comment is included in autogenerated documentation.