A brief introduction to doxygen

1. A brief introduction to doxygen

2. What does a compiler do? • A compiler ignores comments and processes the code. • What does doxygen do? • It ignores the code and processes to comments. • Used to create HTML documentation.

3. Getting started with doxygen • Download 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

4. Usingdoxygen: 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. */ . . .

5. Using doxygen: document every class //---------------------------------------------------------------------- /** \brief JImageViewer class. * * Longer description goes here. */ public class JImageViewer extends JFrame implements ActionListener { . . .

6. 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]); } }

7. 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 //----------------------------------------------------------------------

8. Not every comment should be a doxygen comment. Required: • 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.)

9. 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; …

13. Summary of most useful tags \file \author \brief \param \returns \todo (not used in assignments) And many, many others.