[Nfb-science] Using doxygen as a blind software engineer

[John Miller]

Hello,
 
This is John Miller. I would like to hear back from any blind software engineers who have entered comments made for doxygen. Please send me an email to johnmillerphd at hotmail.com. The question is how to easily enter doxygen comments and how to verify as a blind person that the generated HTML pages contain the desired  information.
 
doxygen is a program that creates HTML files describing a software program. The HTML files have a section identifying all variables and linking each variable with its comment. The HTML files also have a section listing all functions. Each function has a function header comment. Each function also may have block comments inside the function. The HTML file creates documentation for each function listing both the function header comment and all block comments inside the function. Knowing just what to write and what will appear in the HTML files is a little bit tricky. Reading the HTML files in ASCII text is very cumbersome. The source code for the HTML files contains much distracting markup. doxygen can be useful for creating documentation. It can also be useful for providing a second person a description of the source code in the HTML files without giving the person the source  code itself. It is helpful for generating a function call diagram.
 
As you will remember, comments in c++ begin with // and c-style comments begin with /* and end with */. Doxygen comments have a few more rules. If these rules are not followed precisely then even though a comment is a valid c or c++ comment it will not appear in the doxygen  documentation. The comment for the intended variable will not display correctly. Instead a comment for a different variable may be associated with the intended variable or the comment is omitted. Below you can find a snippet of source code for which doxygen will make a set of HTML documentation pages. After the source code I paste what part of the HTML pages look like visually.
Note that all the lines in the block comment before the enum, for example, appear in the web browser as text wrapped. That means it may appear as multiple lines but the web browser ignores the carriage returns in the block comment itself. The comments that begin with /// each appear in the HTML pages on a new line.
 
sample code including doxygen comments:
/**
 * An example enumeration
 * second line of comment
 */
typedef enum
{
FIRST_VAL=0, /**< first enum comment */
SECOND_VAL   /**< second enum comment */
} myEnum;
/**
 * An example structure
 * second line of comment
 */
typedef struct
{
int variable1; /**< first struct element comment */
int variable2;   /**< second struct element comment */
} myStruct;
int globalVar; /**< a global variable */
/**
 * This function gets called in the main test function
 *
 * @param[in] variable1, variable2, variable3
 * @param[out] none
 * @return void
 * @author John Miller
 */
void myFunc(int variable1, int variable2, int variable3)
{
int localVariable;
/** 
 * a multi line comment
 * more of the multi line comment
 */
localVariable = 1;
//! now assign a variable to the value of 2
localVariable = 2;
/// now assign a variable to the value of 3
localVariable = 3;
}
 
This is what doxygen output looks like:
Data Structures
struct myStruct
Enumerations 
enum myEnum { FIRST_VAL =0, SECOND_VAL }
Functions
void myFunc (int variable1, int variable2, int variable3)
Variables
int globalVar
Enumeration Type Documentation
enum myEnum
An example enumeration second line of comment
Table named Enumerator
firstColumn,secondColumn
FIRST_VAL,first struct element comment
SECOND_VAL,second struct element comment
Function Documentation
void myFunc (int variable1, 
             int variable2, 
             int variable3 
            )
Parameters
   [in] variable1,variable2,variable3
   [out] none
Returns
    void 
Author
    John Miller 
a multi line comment more of the multi line comment
 
now assign a variable to the value of 2
 
now assign a variable to the value of 3 

Variable Documentation
int globalVar
a global variable
 
very best,
John