Dolphin 8: autogenerated documentation

AlexT posted 14th of June 2011 in Dolphin.pro News. 10 comments.

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
 * @{
 */
and the following footer (closing @defgroup definition):
/** @} */ 
@defgroup can vary depending on particular files, refer to the next section for more info.

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
so every list item must begin with dash (-)

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

Use @sections keyword for different sections in the documentation block.
For example:
/**
 * 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
 *
 */
    
Standard sections are:
  • @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.
will be transformed to:
My class codeIt is used for some purpose.
So, to make proper formatting you need to write it the following way:
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.

 
Recommended by
 
 
Comments
·Oldest
·Top
Please login to post a comment.
tomakali
hmmm... im dreaming that you will compile your own libraries and provide an api for that :/
DosDawg
so how would this be justified or adhered to on encoded releases, where a developer uses ioncube or zend to encode their source on commercial releases?
dolphin_jay
I guess you got a good point there.
DosDawg
one other thought that came to my mind, is when considering minifying, one of the recommended solutions is to remove all comments and unnecessary characters. so when dealing with thousands of lines of code and functions and classes, should this not be something that is provided not as part of the release, but part of the documentation that is subsequent as a standard for the release of commercial works and or core works?

where i know it is the intent to lighten the load on the dolphin environment, see more when considering the number of files that are part of a default release, and i have no idea how many lines of code make up the functionality overall, but i do know that there is an enormous number of files. exactly what would be the weight of adding comments such as you have prescribed here. yes comments are great, but they would also suffice if it was in document form which would be outside the footprint of the application?

this all sounds like a good idea, but i also see where it can cause a precise amount of issues.
DosDawg
considering just this line:

define('BX_DATA_INT', 3); ///< integer date type

the weight of your comment is nearly equal to that of your required source?
source = 25 characters
comment = 24 characters

so with this concept you are increasing the file size on all declared variables and constants by nearly 100%

so lets look at even the use of the BX_ could you not write a constant that would prepend the BX_ and take out those three characters being declared each time?
or substitue see more the entire BX_DATA declaration
this eliminates 7 characters if you can manage that one. i know it seems trivial, but increasing a file size just for specified comments doesnt seem like its driving in the direction of decreasing the footprint and/or optimization performance?
AlexT
Please don't comment the things you are unaware at all !
DosDawg
really? and how is it that i am unaware? i am asking a question, and clearly i am aware of it, as i inquired from the post. so explain how this is being unaware?

im asking a question, are you able to provide the answer?
dolphin_jay
Seems like its all question to me. Notice the question marks after every sentence ? Why would you respond like that when someone is asking for information about something ?

How could he possibly know anything about it when you yourself just wrote it a few days ago.
mscott
Damn, I've been away for a year or two.. nice to see Boonex is still offering top notch customer support haha.
 
 
Below is the legacy version of the Boonex site, maintained for Dolphin.Pro 7.x support.
The new Dolphin solution is powered by UNA Community Management System.
PET:0.14166903495789