学习doxygen 1. 安装与注释风格

doxygen文档地址：http://www.stack.nl/~dimitri/doxygen/manual/index.html

安装doxygen

git clone https://github.com/doxygen/doxygen.git
cd doxygen
mkdir build
cd build
cmake -G "Unix Makefiles" ..
make
make install

注释风格

doxygen支持很多注释风格，这里采用JavaDoc风格，其它支持的风格见：
http://www.stack.nl/~dimitri/doxygen/manual/docblocks.html#specialblock

/**
 * ... JavaDoc风格 ...
 */

中间的星号可以省略，因此以下形式也正确：

/**
 ... JavaDoc风格 ...
*/

在语句块后注释

int var; /**< Detailed description after the member */

brief

从@brief到本段结束都是brief

/** @brief 这里是brief
 *      这里还是brief.
 *
 *  这里是detail.
 */

如果在配置文件中将JAVADOC_AUTOBRIEF设置为YES，则第一句是detail，第一句是指在第一个英文句号处结束。

Markdown

doxygen注释块中支持markdown语法

例子1

/**
 *  A test class. A more elaborate class description.
 */
class Javadoc_Test
{
  public:
    /** 
     * An enum.
     * More detailed enum description.
     */
    enum TEnum { 
          TVal1, /**< enum value TVal1. */  
          TVal2, /**< enum value TVal2. */  
          TVal3  /**< enum value TVal3. */  
         } 
       *enumPtr, /**< enum pointer. Details. */
       enumVar;  /**< enum variable. Details. */
       
      /**
       * A constructor.
       * A more elaborate description of the constructor.
       */
      Javadoc_Test();
      /**
       * A destructor.
       * A more elaborate description of the destructor.
       */
     ~Javadoc_Test();
    
      /**
       * a normal member taking two arguments and returning an integer value.
       * @param a an integer argument.
       * @param s a constant character pointer.
       * @see Javadoc_Test()
       * @see ~Javadoc_Test()
       * @see testMeToo()
       * @see publicVar()
       * @return The test results
       */
       int testMe(int a,const char *s);
       
      /**
       * A pure virtual member.
       * @see testMe()
       * @param c1 the first argument.
       * @param c2 the second argument.
       */
       virtual void testMeToo(char c1,char c2) = 0;
   
      /** 
       * a public variable.
       * Details.
       */
       int publicVar;
       
      /**
       * a function variable.
       * Details.
       */
       int (*handler)(int a,int b);
};

例子2

/** @file structcmd.h
    @brief A Documented file.
    
    Details.
*/
/** @def MAX(a,b)
    @brief A macro that returns the maximum of \a a and \a b.
   
    Details.
*/
/** @var typedef unsigned int UINT32
    @brief A type definition for a .
    
    Details.
*/
/** @var int errno
    @brief Contains the last error code.
    @warning Not thread safe!
*/
/** @fn int open(const char *pathname,int flags)
    @brief Opens a file descriptor.
    @param pathname The name of the descriptor.
    @param flags Opening flags.
*/
/** @fn int close(int fd)
    @brief Closes the file descriptor \a fd.
    @param fd The descriptor to close.
*/
/** @fn size_t write(int fd,const char *buf, size_t count)
    @brief Writes \a count bytes from \a buf to the filedescriptor \a fd.
    @param fd The descriptor to write to.
    @param buf The data buffer to write.
    @param count The number of bytes to write.
*/
/** @fn int read(int fd,char *buf,size_t count)
    @brief Read bytes from a file descriptor.
    @param fd The descriptor to read from.
    @param buf The buffer to read into.
    @param count The number of bytes to read.
*/
#define MAX(a,b) (((a)>(b))?(a):(b))
typedef unsigned int UINT32;
int errno;
int open(const char *,int);
int close(int);
size_t write(int,const char *, size_t);
int read(int,char *,size_t);