A brief introduction to A brief introduction to doxygendoxygen

What does a compiler do?What does a compiler do?

A compiler ignores comments and A compiler ignores comments and processes the code.processes the code.

What does doxygen do?What does doxygen do?– It ignores the code and processes to It ignores the code and processes to

comments.comments.– Used to create HTML documentation.Used to create HTML documentation.

Getting started with doxygen Download from doxyDownload from doxygen.org

– Also on scott in /home/ggrevera/doxygen/bin 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 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 global and class member (and global and

static variable in C/C++)static variable in 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 be a Not every comment should be a doxygen comment.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 variable(in C/C++) every static and/or global variable

Use regular, plain comments in the body of a Use regular, plain comments in the body of a function/method. (One exception is the \function/method. (One exception is the \todo.)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 tagsSummary of most useful tags

\file\file\author\author\brief\brief\param\param\returns\returns\todo (not used in assignments)\todo (not used in assignments)

And many, many others.And many, many others.