怎样注释C/C++代码

简述(brief description)和详述(detailed description)

 

详述的几种方式

 

1. JavaDoc style

     /**

      * ... text ...

      */

2. Qt style
    /*!

     * ... text ...

     */

3. C++ comment style
    
    

     
     
    ///                            

    /// ... text ... 

    ///

    or 

    //! 

    //! ... text ...

    //!

4. Block style
    /********************************************//**

     *  ... text

     ***********************************************/

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


    or 
    /

    /// ... text ...

    

简述的几种方式

1.  /brief

 command


    /*! /brief Brief description.

     *         Brief description continued.

     *

     *  Detailed description starts here.

     */

2. 设置JAVADOC_AUTOBRIEF
， 第一句作为描述
    /** Brief description which ends at this dot. Details follow

     *  here.

     */

3. C++ style   
   /// Brief description.

   /** Detailed description. */

   or 
   //! Brief descripion.



   //! Detailed description 

   //! starts here

示例， 使用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);
};
  













JavaDoc style, JAVADOC_AUTOBRIEF
 set to 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 and returning 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);
};

 







参考 http://www.stack.nl/~dimitri/doxygen/docblocks.html