1 / 16

A brief introduction to javadoc and doxygen

A brief introduction to javadoc and doxygen. Cont’d. doxygen.

diem
Download Presentation

A brief introduction to javadoc and doxygen

An Image/Link below is provided (as is) to download presentation Download Policy: Content on the Website is provided to you AS IS for your information and personal use and may not be sold / licensed / shared on other websites without getting consent from its author. Content is provided to you AS IS for your information and personal use only. Download presentation by click this link. While downloading, if for some reason you are not able to download a presentation, the publisher may have deleted the file from their server. During download, if you can't get a presentation, the file might be deleted by the publisher.

E N D

Presentation Transcript

  1. A brief introduction to javadoc and doxygen Cont’d.

  2. doxygen

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

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

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

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

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

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

  9. 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.)

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

  11. 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).

  12. 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/Doxygen-Filter-Perl-1.50/lib/Doxygen/Filter/Perl.pm for Perl and doxygen.

  13. Inheritance and collaboration diagrams Automatically generated by doxygen. Example is from ITK’s AbsImageFilter (see http://www.itk.org/Doxygen43/html/classitk_1_1AbsImageFilter.html). Inheritance: Collaboration:

More Related