DoxyGen文档之四

类别:软件工程 点击:0 评论:0 推荐:
  第二章:Documenting the code 特殊的注释

一种特殊的注释是带有一些额外标记的C/C++注释块,这样doxygen就知道需要将其加入到文档中了。

对于每个代码块都有两种注释,这两种注释组成了文档:一种是brief 描述另一种是detailed 描述,都是可选的。可以有多于一个的brief 描述和detailed 描述,但是是无效的。

顾名思义,一个brief描述只有一行,而detail描述则是更长更详尽的文档。

有几种方式添加一个detail描述:

1.  使用JavaDoc风格,包含一个C风格的注释块

/**

 * ... text ...

 */

2.  使用Qt风格

/*!

 * ... text ...

 */

这中间的*都是可选的,因此

/*!

 ... text ...

*/

也是有效的

3.  第三种风格是至少使用两个C++注释行,每行加多一个/或者是!

///

/// ... text ...

///

//!

//!... text ...

//!

4.     有些人喜欢将注释变得比较醒目,可以这样来作

/////////////////////////////////////////////////

/// ... text ...

/////////////////////////////////////////////////

有以下方式添加brief注释

1.  一种是在上述注释块中使用\brief,然后一个空行后跟着Detail注释

/*! \brief Brief description.

 *         Brief description continued.

 *

 *  Detailed description starts here.

 */

2.  如果配置文件中JAVADOC_AUTOBRIEF被设为YES,则使用JavaDoc风格注释块将自动开始一个brief注释,这个注释将以“.”后跟一个空格或新行结束

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

 *  here.

 */

同样可以应用到多行的C++风格注释中

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

/// here.

3.  第三种可以使用一种特殊的C++风格注释,每次不超过一行

/// Brief description.

/** Detailed description. */

//! Brief descripion.

 

//! Detailed description

//! starts here.

注意后一个例子中的空行,Doxygen用他来分开brief描述和detail描述。在此情况下JAVADOC_AUTOBRIEF也应设置为NO

如你所见,doxygen很灵活,下面这种写法是非法的

//! Brief description, which is

//! really a detailed description since it spans multiple lines.

/*! Oops, another detailed description!

 */

因为doxygen只允许一个brief和一个detail描述

更进一步,如果一个brief描述在 declaration前,一个在code前,那么将使用declaration前的那个。对于detailed描述也是如此,definition前的那个比declaration前的有高优先级。

这里有一段Qt风格的C++例子:(注意这一段需要仔细研究,改写掉注释宏的代码)

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

};

 

这些单行注释包括一个brief描述,而multi-line注释块包含一个更详细的描述。

Brief描述包含在class,namespace或file的member的预览中,小号的斜体字(通过将BRIEF_MEMBER_DESC设置为NO可以关掉这些brief描绘)。缺省的brief描述是detailed描述的第一句话(通过将REPEAT_BRIEF设置为NO可以改变此设置)。在Qt风格中brief和detailed都是可选

缺省的,JavaDoc风格的注释块和Qt风格的注释同样有效。这并不是根据JavaDoc规格的,而是注释的第一行被认为是brief描述。要打开此设置,将JAVADOC_AUTOBRIEF设置为YES。用一个“.”来作分隔,或者使用一个“\”:

  /** Brief description (e.g.\ using only a few words). Details follow. */

设置JavaDoc style和JAVADOC_AUTOBRIEF为YES:

/**

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

         }

       *enumPtr, /**< enum pointer. Details. */

       enumVar;  /**< enum variable. Details. */

      

      /**

       * 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 & return an integer value.

       * @param a an integer argument.

       * @param s a constant character pointer.

       * @see Test()

       * @see ~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);

};

和大多数文档系统不一样,doxygen也允许你将将member注释放在definition之前。这种方式下,注释可以写在.cpp文件中而非.h文件中。这样头文件就显得比较简洁,同时member前也直接有注释。作为一种妥协,brief描述可以放在member的declaration前,detailed描述可以放在definition前。

本文地址:http://com.8s8s.com/it/it37423.htm