C++设计开发规范(附录A)：注释详解

 

附录A   注释详解

n 注释interface/class/enum/struct etc.

/*! /interface IExporter

          For the usage of exporting the file to PDF/PS/XML etc.

       */

       interface IExporter

       {

       }

       /*! /class Exporter

          For the usage of exporting the file to PDF/PS/XML etc.

       */

       class Exporter : public IExporter

       {

       }

       /*! /enum kFileType

          The file type.

       */

       enum kFileType

       {

}

/*! /struct PageSetting

          The setting for the creation of a page.

       */

       struct PageSetting

       {

}

n 注释函数

//! Export the file to PDF

/*!

    /param filename The full path of the file being exported

    /param pdfFilename The full path of the exported PDF file

    /return True for success,false for failure.

*/

bool ExportPDF(const wchar_t* filename,const wchar_t* pdfFilename);

n 为函数添加示例代码注释

//! Export the file to PDF

/*!

    /param filename The full path of the file being exported

    /param pdfFilename The full path of the exported PDF file

    /return True for success,false for failure.

    /code

           IExporter* pExporter = new PDFExporter();

           pExporter-> ExportPDF(filename,pdfFilename);

    /endcode

*/

bool ExportPDF(const wchar_t* filename,const wchar_t* pdfFilename);

n 为public/protected字段或枚举值添加注释

/*! /struct PageSetting

       The setting for the creation of a page.

    */

    struct PageSetting

    {

    double Height;              //!< The height of the page

    double Width;        //!< The width of the page

}

/*! /enum kCharacterCodeType

        The code type of the character .

*/

enum kCharacterCodeType

{

    kCharacterCodeType_Unicode,         //!< Unicode

      kCharacterCodeType_Ansi,              //!< Ansi

     kCharacterCodeType_GBK,             //!< GBK

}