doxygen

因为代码量大，有些东西前面写后面忘，需要一些注释，而不规范、无结构的注释起不了大作用，因此选用鼎鼎大名的doxygen.

1.setup 直接选用xp 的 binary。因为暂时还没有其它需要，所以没有下载若干辅助软件。

2.documenting the code

   注释被分为三类: brief description and detailed description for code item, and in body description.

Detailed descripting way:

1. /**..

     * As Visual Assist X supplies.  JavaDoc Style

    */

2.

/*!

* Qt Style

*/

3

///(!)

///(!)

///(!)

Some people like to make their comment blocks more visible in the documentation. For this purpose you can use the following:

/********************************************//**
 *  ... text
 ***********************************************/

(note the 2 slashes to end the normal comment block and start a special comment block).

or

/////////////////////////////////////////////////
/// ... text ...
/////////////////////////////////////////////////

Brief descripting:

1. One could use the \brief command with one of the above comment blocks. This command ends at the end of a paragraph, so the detailed description follows after an empty line.

   Here is an example:

   /*! \brief Brief description.
    *         Brief description continued.
    *
    *  Detailed description starts here.
    */
   

2. If JAVADOC_AUTOBRIEF is set to YES in the configuration file, then using JavaDoc style comment blocks will automatically start a brief description which ends at the first dot followed by a space or new line. Here is an example:

   /** Brief description which ends at this dot. Details follow
    *  here.
    */
   

   The option has the same effect for multi-line special C++ comments:

   /// Brief description which ends at this dot. Details follow
   /// here.
   

3. A third option is to use a special C++ style comment which does not span more than one line. Here are two examples:

   /// Brief description.
   /** Detailed description. */
   

   or

   //! Brief description.
   
   //! Detailed description 
   //! starts here.

Here is an example of a documented piece of C++ code using the Qt style:

//!  A test class. 
/*!
  A more elaborate class description.
*/

class Test
{
  public:

    //! An enum.
    /*! More detailed enum description. */
    enum TEnum { 
                 TVal1, /*!< Enum value TVal1. */  
                 TVal2, /*!< Enum value TVal2. */  
                 TVal3  /*!< Enum value TVal3. */  
               } 
         //! Enum pointer.
         /*! Details. */
         *enumPtr, 
         //! Enum variable.
         /*! Details. */
         enumVar;  
    
    //! A constructor.
    /*!
      A more elaborate description of the constructor.
    */
    Test();

    //! A destructor.
    /*!
      A more elaborate description of the destructor.
    */
   ~Test();
    
    //! A normal member taking two arguments and returning an integer value.
    /*!
      \param a an integer argument.
      \param s a constant character pointer.
      \return The test results
      \sa Test(), ~Test(), testMeToo() and publicVar()
    */
    int testMe(int a,const char *s);
       
    //! A pure virtual member.
    /*!
      \sa 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);
}

觉得这个例子中的注释方式不错：不用敲太多次键盘，决定选用这种。

 

Putting documentation after members

If you want to document the members of a file, struct, union, class, or enum, and you want to put the documentation for these members inside the compound, it is sometimes desired to place the documentation block after the member instead of before. For this purpose you have to put an additional < marker in the comment block. Note that this also works for the parameters of a function.

Documentation at other places

上面说的都是在代码块前面放注释，Doxygen也允许在其它任何地方注释，但代价是要使用结构化命令。

Structural commands (like all other commands) start with a backslash (\), or an at-sign (@) if you prefer JavaDoc style, followed by a command name and one or more parameters. For instance, if you want to document the class Test in the example above, you could have also put the following documentation block somewhere in the input that is read by doxygen:

/*! \class Test
    \brief A test class.

    A more detailed class description.
*/

Here the special command \class is used to indicate that the comment block contains documentation for the class Test. Other structural commands are:

• \struct to document a C-struct.
• \union to document a union.
• \enum to document an enumeration type.
• \fn to document a function.
• \var to document a variable or typedef or enum value.
• \def to document a #define.
• \typedef to document a type definition.
• \file to document a file.
• \namespace to document a namespace.
• \package to document a Java package.
• \interface to document an IDL interface.

To document a member of a C++ class, you must also document the class itself. The same holds for namespaces. To document a global C function, typedef, enum or preprocessor definition you must first document the file that contains it (usually this will be a header file, because that file contains the information that is exported to other source files).

Let's repeat that, because it is often overlooked: to document global objects (functions, typedefs, enum, macros, etc), you must document the file in which they are defined. In other words, there must at least be a

/*! \file */ 

or a

/** @file */ 

line in this file.

例子：

/*! \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);

但这么复杂的用法我应该不会用到，因为这些注释目前只有我一个人会去看。。

而且，我目前只要写注释就够了，至于产生为各种格式的文档是以后的事情，因此配置之后可用时再补上。