A brief A brief introduction to introduction to

javadoc and javadoc and doxygendoxygenCont’d.Cont’d.

DOXYGENDOXYGEN

““Doxygen is the de facto standard tool for Doxygen is the de facto standard tool for generating documentation from annotated generating documentation from annotated C++ sources, but it also supports other C++ sources, but it also supports other popular programming languages such as popular programming languages such as C, Objective-C, C#, PHP, Java, Python, IDL C, Objective-C, C#, PHP, Java, Python, IDL (Corba and Microsoft flavors), Fortran, (Corba and Microsoft flavors), Fortran, VHDL, Tcl, and to some extent D.”VHDL, Tcl, and to some extent D.”

-http://www.stack.nl/~dimitri/doxygen/-http://www.stack.nl/~dimitri/doxygen/

Getting started with doxygen

1.1. Download from doxyDownload from doxygen.org Also on scott in /home/ggrevera/doxygen/bin

2. Do this only once in directory (folder) containing your source code:doxygen –g

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

3. 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 ImageData.java * \brief contains ImageData class definition (note that this * class is abstract) * * <more verbose description here> * \author 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 Using doxygen: document everyevery class member (and class member (and

global and static variable in global and static variable in C/C++)C/C++)

//---------------------------------------------------------------------- int mW; ///< image widthint mH; ///< image heightint mMin; ///< min image valueint mMax; ///< max image valueint[] mImage; ///< actual image data//----------------------------------------------------------------------

Not every comment should Not every comment should be a doxygen comment.be a doxygen comment.

Required:Required:1.1. every fileevery file

2.2. every function/methodevery function/method

3.3. every class member (data)every class member (data)

4.4. (in C/C++) every static and/or global (in C/C++) every static and/or global variablevariable

Use regular, plain comments in the body of Use regular, plain comments in the body of a function/method. (One exception is a function/method. (One exception is the \todo.)the \todo.)

int mColorImageData[][][]; int mColorImageData[][][]; ///< should be mColorImageData[mH][mW][3]///< should be mColorImageData[mH][mW][3] //----------------------------------------------------------------------//---------------------------------------------------------------------- /** \brief Given a buffered image, this ctor reads the image data, stores /** \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 raw pixel data in an array, and creates a displayable version of * the image. Note that this ctor is protected. The user should only * the image. Note that this ctor is protected. The user should only * use ImageData.load( fileName ) to instantiate an object of this type.* use ImageData.load( fileName ) to instantiate an object of this type. * \param bi buffered image used to construct this class instance* \param bi buffered image used to construct this class instance * \param w width of image* \param w width of image * \param h height of image* \param h height of image * \returns nothing (constructor)* \returns nothing (constructor) */*/ protected ColorImageData ( final BufferedImage bi, final int w, final int h ) {protected ColorImageData ( final BufferedImage bi, final int w, final int h ) { mW = w;mW = w; mH = h;mH = h; mOriginalImage = bi;mOriginalImage = bi; mIsColor = true;mIsColor = true; //format TYPE_INT_ARGB will be saved to mDisplayData//format TYPE_INT_ARGB will be saved to mDisplayData mDisplayData = mOriginalImage.getRGB(0, 0, mW, mH, null, 0, mW);mDisplayData = mOriginalImage.getRGB(0, 0, mW, mH, null, 0, mW); mImageData = new int[ mW * mH * 3 ];mImageData = new int[ mW * mH * 3 ]; mMin = mMax = mDisplayData[0] & 0xff;mMin = mMax = mDisplayData[0] & 0xff; for (int i=0,j=0; i<mDisplayData.length; i++) {for (int i=0,j=0; i<mDisplayData.length; i++) { mDisplayData[i] &= 0xffffff; mDisplayData[i] &= 0xffffff; //just to insure that we only have 24-bit rgb//just to insure that we only have 24-bit rgb final int r = (mDisplayData[i] & 0xff0000) >> 16;final int r = (mDisplayData[i] & 0xff0000) >> 16; final int g = (mDisplayData[i] & 0xff00) >> 8;final int g = (mDisplayData[i] & 0xff00) >> 8; final int b = mDisplayData[i] & 0xff;final int b = mDisplayData[i] & 0xff; if (r<mMin) mMin = r;if (r<mMin) mMin = r; if (g<mMin) mMin = g;if (g<mMin) mMin = g;……

Summary of most useful Summary of most useful tags/commandstags/commands

\file\file\author\author\brief\brief\param\param\returns\returns\todo\todo

And many, many others (more than 150; see And many, many others (more than 150; see http://www.stack.nl/~dimitri/doxygen/manhttp://www.stack.nl/~dimitri/doxygen/manual/commands.html).ual/commands.html).

Language specific notesLanguage specific notes

Tags may start with either \ or @ Tags may start with either \ or @ (important for PHP as it uses \ as (important for PHP as it uses \ as part of the language so you must use part of the language so you must use @ for PHP).@ for PHP).

See See http://search.cpan.org/~jordan/Doxyhttp://search.cpan.org/~jordan/Doxygen-Filter-Perl-1.50/lib/Doxygen/gen-Filter-Perl-1.50/lib/Doxygen/Filter/Perl.pm for Perl and doxygen.Filter/Perl.pm for Perl and doxygen.

Inheritance and Inheritance and collaboration diagramscollaboration diagrams

Automatically generated by doxygen. Automatically generated by doxygen. Example is from ITK’s AbsImageFilter Example is from ITK’s AbsImageFilter (see (see http://www.itk.org/Doxygen43/html/classithttp://www.itk.org/Doxygen43/html/classitk_1_1AbsImageFilter.html).k_1_1AbsImageFilter.html).

Inheritance:Inheritance:

Collaboration:Collaboration: