A brief introduction to
javadoc and doxygen
Cont’d.
DOXYGEN
“Doxygen is the de facto standard tool for
generating documentation from annotated C++
sources, but it also supports other popular
programming languages such as C, Objective-C,
C#, PHP, Java, Python, IDL (Corba and
Microsoft flavors), Fortran, VHDL, Tcl, and to
some extent D.”
-http://www.stack.nl/~dimitri/doxygen/
Getting started with doxygen
1.
Download from doxygen.org

2.
Also on scott in /home/ggrevera/doxygen/bin
Do this only once in directory (folder) containing your source
code:
doxygen –g



3.
This creates a doxygen configuration file called Doxyfile which you may edit
to change default options.
Edit Doxyfile and make sure all EXTRACTs are YES
For C (not C++) development, also set OPTIMIZE_OUTPUT_FOR_C =
YES
Then whenever you change your code and wish to update the
documentation:
doxygen

which updates all documentation in HTML subdirectory
Using doxygen: document every
(source code) file
/**
* \file
* \brief
*
*
*
* \author
*/
.
.
.
ImageData.java
contains ImageData class definition (note that this
class is abstract)
<more verbose description here>
George J. Grevera, Ph.D.
Using doxygen: document every
class
//---------------------------------------------------------------------/** \brief JImageViewer class.
*
* Longer description goes here.
*/
public class JImageViewer extends JFrame implements ActionListener {
.
.
.
Using doxygen: document every
function
//---------------------------------------------------------------------/** \brief Main application entry point.
*
* \param args Each image file name in args will cause that image
* to be displayed in a window.
* \returns nothing
*/
public static void main ( String[] args ) {
if (args.length==0) {
new JImageViewer();
} else {
for (int i = 0; i < args.length; i++)
new JImageViewer( args[i] );
}
}
Using doxygen: document every
class member (and global and static
variable in C/C++)
//---------------------------------------------------------------------int mW;
///< image width
int mH;
///< image height
int mMin;
///< min image value
int mMax;
///< max image value
int[] mImage;
///< actual image data
//----------------------------------------------------------------------
Not every comment should be a
doxygen comment.
Required:
1.
2.
3.
4.
every file
every function/method
every class member (data)
(in C/C++) every static and/or global variable
Use regular, plain comments in the body of a
function/method. (One exception is the \todo.)
int mColorImageData[][][]; ///< should be mColorImageData[mH][mW][3]
//---------------------------------------------------------------------/** \brief Given a buffered image, this ctor reads the image data, stores
* the raw pixel data in an array, and creates a displayable version of
* the image. Note that this ctor is protected. The user should only
* use ImageData.load( fileName ) to instantiate an object of this type.
* \param bi buffered image used to construct this class instance
* \param w width of image
* \param h height of image
* \returns nothing (constructor)
*/
protected ColorImageData ( final BufferedImage bi, final int w, final int h ) {
mW = w;
mH = h;
mOriginalImage = bi;
mIsColor = true;
//format TYPE_INT_ARGB will be saved to mDisplayData
mDisplayData = mOriginalImage.getRGB(0, 0, mW, mH, null, 0, mW);
mImageData = new int[ mW * mH * 3 ];
mMin = mMax = mDisplayData[0] & 0xff;
for (int i=0,j=0; i<mDisplayData.length; i++) {
mDisplayData[i] &= 0xffffff; //just to insure that we only have 24-bit rgb
final int r = (mDisplayData[i] & 0xff0000) >> 16;
final int g = (mDisplayData[i] & 0xff00) >> 8;
final int b = mDisplayData[i] & 0xff;
if (r<mMin) mMin = r;
if (g<mMin) mMin = g;
…
Summary of most useful
tags/commands
\file
\author
\brief
\param
\returns
\todo
And many, many others (more than 150; see
http://www.stack.nl/~dimitri/doxygen/manual
/commands.html).
Language specific notes

Tags may start with either \ or @ (important for
PHP as it uses \ as part of the language so you
must use @ for PHP).

See http://search.cpan.org/~jordan/DoxygenFilter-Perl-1.50/lib/Doxygen/Filter/Perl.pm for
Perl and doxygen.
Inheritance and collaboration
diagrams

Automatically generated by doxygen. Example is from
ITK’s AbsImageFilter (see
http://www.itk.org/Doxygen43/html/classitk_1_1Abs
ImageFilter.html).
Inheritance:
Collaboration: