Doxygen
Doxygen is a documentation software for a variety of programming languages, including C++, C, Java, Objective-C, PHP, Python, Fortran, and C#.
The creator of Doxygen, Dimitry van Heesch, maitains a Doxygen web site that has latest releases, manuals, mailing lists, articles, and many other resources for Doxygen users and developers.
Contents |
Installation
Doxygen's releases include source distribution, binary distribution for Linux, 32-bit binary distribution for Windows XP/Vista/7, and universal distributions for Mac OS Snow Leopard and Tiger.
- Go to Doxygen soure and binary releases to download the distribution for your operating system. Doxygen has a self-installing archive and a zip file with binaries for Windows.
- Download and install GraphViz (version 2.8 or better is highly recommended). Doxygen can use the dot tool of the GraphViz package to render nicer diagrams (see the HAVE_DOT option in the configuration file).
Getting started
- The executable
doxygenis the main program that parses the sources and generates documentation. - To run
doxygenin a graphical environment, usedoxywizardexecutable, but after you create the configuration file (see next).
Create a configuration file
doxygen uses a configuration file to determine all of its settings. Each project should have its own configuration file. A project may have a single source file or an entire tree of directories with source files.
To create a template configuration file:
- In a Windows terminal (command line) window, go in the root directory of your project. For example:
C:\Documents and Settings\mcs>cd \ C:\>cd web_development\rmhhomebase\rmhproject\rmh20
- Call
doxygenfrom the command line with-goption
C:\web_development\rmhhomebase\rmhproject\rmh20>doxygen -g
-
doxygenproduces the output:
Configuration file '''Doxyfile''' created. Now edit the configuration file and enter doxygen Doxyfile to generate the documentation for your project C:\web_development\rmhhomebase\rmhproject\rmh20>
Doxyfile is the default doxygen configuration file.
Running doxygen and editing Doxyfile
Use doxywizard to edit the Doxyfile configuration file and run doxygen.
doxywizard is a GUI front-end. Start it in a Windows terminal window by calling the program:
C:\web_development\rmhhomebase\rmhproject\rmh20>doxywizard C:\web_development\rmhhomebase\rmhproject\rmh20>
Shortly, doxywizard GUI pops up.
Configuring doxygen
doxywizard interface shows two steps. At Step 1 we specify the working directory from which doxygen will run, and which is the root of project's directory tree. In our example, the working directory is:
C:\web_development\rmhhomebase\rmhproject\rmh20>
This directory has the Doxyfile template you have configured (see above).
Step 2 has three tabs:
- Wizard and Expert to configure
doxygen - Run tab to generate the documentation.
The configuration settings in the Wizard tab are grouped by topics (see list in the left side panel):
- In the Project topic
- Select the directory to scan for source code. In our example, this is the same directory as the project's root directory. '
- Select the directory where
doxygen' will generate the documentation. Create a docs directory in the project's directory structure and point the destination directory to the docs location. - Check Scan recursively to generate documentation for all files in all directories and subdirectories.
- In the Mode topic, select the programming language from the list of supported programming languages.
- In the Output topic, select HTML and check with navigation panel and with search function. Leave LaTex alone for the time being...
- In the Diagrams topic, select the dot tool from the GraphViz package.
Running doxygen
To generate documentation, select the Run tab and click Run doxygen. Sample of output produced by doxygen and shown in the Run tab:
Searching for include files... Searching for example files... Searching for images... Searching for dot files... Searching for msc files... Searching for files to exclude Searching for files to process... Searching for files in directory C:/web_development/rmhhomebase/rmhproject/rmh20 Searching for files in directory C:/web_development/rmhhomebase/rmhproject/rmh20/.settings Searching for files in directory C:/web_development/rmhhomebase/rmhproject/rmh20/database Searching for files in directory C:/web_development/rmhhomebase/rmhproject/rmh20/docs Searching for files in directory C:/web_development/rmhhomebase/rmhproject/rmh20/images Searching for files in directory C:/web_development/rmhhomebase/rmhproject/rmh20/tests Searching for files in directory C:/web_development/rmhhomebase/rmhproject/rmh20/tutorial Searching for files in directory C:/web_development/rmhhomebase/rmhproject/rmh20/tutorial/screenshots Reading and parsing tag files Reading C:/web_development/rmhhomebase/rmhproject/rmh20/about.php... Parsing file C:/web_development/rmhhomebase/rmhproject/rmh20/about.php... Reading C:/web_development/rmhhomebase/rmhproject/rmh20/addWeek.php... Parsing file C:/web_development/rmhhomebase/rmhproject/rmh20/addWeek.php... Reading C:/web_development/rmhhomebase/rmhproject/rmh20/addWeek_newweek.inc... Parsing file C:/web_development/rmhhom ebase/rmhproject/rmh20/addWeek_newweek.inc... Reading C:/web_development/rmhhomebase/rmhproject/rmh20/calendar.inc... Parsing file C:/web_development/rmhhomebase/rmhproject/rmh20/calendar.inc... Reading C:/web_development/rmhhomebase/rmhproject/rmh20/calendar.php... Parsing file C:/web_development/rmhhomebase/rmhproject/rmh20/calendar.php... Reading C:/web_development/rmhhomebase/rmhproject/rmh20/calendarFam.php... Parsing file C:/web_development/rmhhomebase/rmhproject/rmh20/calendarFam.php... Reading C:/web_development/rmhhomebase/rmhproject/rmh20/database/dbDates.php... Parsing file C:/web_development/rmhhomebase/rmhproject/rmh20/database/dbDates.php... Reading C:/web_development/rmhhomebase/rmhproject/rmh20/database/dbinfo.php... Parsing file C:/web_development/rmhhomebase/rmhproject/rmh20/database/dbinfo.php...
To see the generated documentation, click on Show HTML Output in the Runtab.
Documenting PHP source code
Follow Drupal's standards for documenting PHP code. We are particularly interested in documenting:
Documenting files
Each file must start with a comment describing what the file does. For example:
/** * @file * Controls database operations on the dbPersons table. * * Copyright 2008 by Oliver Radwan, Maxwell Palmer, Nolan McNair, * Taylor Talmage, and Allen Tucker. This program is part of RMH Homebase. * RMH Homebase is free software. It comes with absolutely no warranty. * You can redistribute it and/or modify it under the terms of the GNU * General Public License as published by the Free Software Foundation * (see <http://www.gnu.org/licenses/ for more information). * * @version May 1, 2008 * @author Oliver Radwan and Allen Tucker */
- The line immediately following the @file directive is a summary that is shown in the list of all files in the generated documentation. If the line begins with a verb, that verb should be present tense.
- After the summary, there is a blank line followed by the copyright notice.
- Directives @version and @author concludes the file documentation block.
Documenting functions and methods
Each function (or method) has a block comment with the following content:
- Purpose of the function. Use present tense to say what the function does.
- @param or @return directives, if applicable.
- @param directive must list the data type of the parameter (int, string, boolean, array, object (if its class is not known, or its class).
- End each statement with a period.
This is an example for the delete_dbShifts( ) function in dbShift.php module from RMH 2.0 project.
/**
* Deletes a shift from the Shift table in the database.
* @param Shift $s The shift to be deleted.
* @return TRUE on success. FALSE on failure.
*/
function delete_dbShifts($s) {
if (!$s instanceof Shift) {
echo("Invalid argument for delete_dbShifts function call");
return false;
}
connect();
$query="DELETE FROM dbShifts WHERE id=\"".$s->get_id()."\"";
mysql_close();
$result=mysql_query($query);
if(!$result) {
echo "Unable to delete from dbShifts ".$s->get_id().mysql_error();
mysql_close();
return false;
}
return true;
}
Documenting classes
After the file block comment, just before the class header, write a class block comment as follows:
/**
* Represents person data stored in the dbPersons table.
*/
class Person {
...
