DOXYGEN简明实用教程_doxygen不显示制作者-优快云博客

本文介绍Doxygen工具的基本使用方法，包括各类注释的撰写规范，帮助开发者高效地为代码生成文档。

摘要生成于 C知道，由 DeepSeek-R1 满血版支持，前往体验 >

代码写多了难免需要做文档，给自己还是给别人看都需要如此，这次XBOX360制作，前期没怎么写注释，回头改Bug都要猜半天自己写的代码是什么意思。更别提别人写的东西，100行代码也没有一句注释，幸好不是我维护，否则要疯掉了。

花了一天功夫尝试了一下Doxygen的使用，还好不难，但是有些磕磕绊绊，它自己的文档也说不清楚，网上搜出来的教程也只是给出样子，遇到的问题还是靠自己尝试了几十次才搞定。

不管如何，常用的东西都可以弄出来了。贴在下面：

-----------------------------------------------------------------------------------

1.所有注释都可以使用///开始(C++风格)。

2.类体前必须加上///描述，否则会产生警告【Compound 类名 is not documented】
描述中最好不要带有此类的类名，否则会产生两个链接(但指向同一个文件)影响美观。

3.public和protected会自动生成，但是private要在Expert的Build选项里勾中EXTRACT_PRIVATE，static成员也是如此。

4.函数注释方式
   /// Constructor【函数描述】
   /// @param [in] pos       The position of Camera in world coordinate         【参数描述1】
   /// @param [in] lookat    The point Camera looks at in world coordinate   【参数描述2】
   BaseCamera( const D3DXVECTOR3& pos, const D3DXVECTOR3& lookat );

5.变量注释方式
   D3DXVECTOR3 m_Position;   /*!< Camera position point in world coordinate */   或
   D3DXVECTOR3 m_Position;   ///< Camera position point in world coordinate
两种方式产生的结果不同。前者会单独产生一块Member Data Documentation注释，后者会在Pubilc/Protected/Private Attributes变量描述后紧跟注释。

6.@参数和\参数相同

7.产生描述顺序和注释顺序相同，一般风格为

   /// 函数描述
   /// @param    参数描述
   /// @return    返回值描述
   /// @retval    返回值1    返回值1描述
   /// @retval    返回值2    返回值2描述
   /// @remarks    注意事项
   /// @note   注意事项，功能同@remarks,显示字样不同
   /// @par   自定义图块，后面可跟示例代码之类
   /// @code(必须使用@endcode结束)
   /// 示例代码(无需缩进)
   /// @endcode
   /// @see    其他参考项【产生指向参考的链接】
   函数代码声明

8.特殊符号
   /// -       产生一个黑色圆点

9.定义在类体里面的enum
   /// Camera types
   enum CAMERA_TYPE
   {
       CAMERA_FIRST_VIEW,/*!< Camera that looks from the first view */
       CAMERA_MODEL_VIEW,///< Camera that looks from the third view
   };
   两种风格相同。

以下开始的项都是全局非类内定义，在文件最开始(我尝试是在include之前) 必须加上【/// \file 文件名】，否则不会生成注释【没有File Member页】。

10. 定义在文件里面的宏
    #define CAMERA_TYPE_NUMBER     ///< The number of camera types.       或
   #define CAMERA_TYPE_NUMBER     /*!< The number of camera types. */
风格说明见5。

11. 非类内enum定义同10.       两种风格相同。见9。
12. 非类内typedef定义同10.    风格说明见5。

-----------------------------------------------------------

编写正确格式的注释说明

头文件头部注释规范，注释必须列出版权说明、版本号、生成日期、作者、内容、功能、与其它文件的关系、修改日志等，头文件的注释中还应有函数功能简要说明：

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

/// Copyright (C), 2005-2007.

/// \file  WindowsNT

  /// \brief Windows Nice Try.

/// \author Bill Gates

  /// \author Several species of small furry animals gathered together

  ///          in a cave and grooving with a pict.

  /// \version 4.0

  /// \date    1996-1998

  /// \warning This class may explode in your face.

  /// \warning If you inherit anything from this class, you're doomed.

  /// \ClassList:主要函数列表，每条记录应包括函数名及功能简要说明

/// 1. ....

 /// \History: 修改历史记录列表，每条修改记录应包括修改日期、修改者及修改内容简述

///

/// Hsz 2005/4/12 1.0 build this moudle

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

源文件头部注释规范，列出：版权说明、版本号、生成日期、作者、模块目的/功能、主要函数及其功能、修改日志等。示例：下面这段源文件的头注释比较标准，当然，并不局限于此格式，但上述信息建议要包含在内：

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

/// Copyright (C), 2005-2007,

/// \file  WindowsNT

  /// \brief Windows Nice Try.

  /// \author Bill Gates

  /// \author Several species of small furry animals gathered together

  ///          in a cave and grooving with a pict.

  /// \version 4.0

  /// \date    1996-1998

  /// \warning This class may explode in your face.

  /// \warning If you inherit anything from this class, you're doomed.

  /// \Function List:主要函数列表，每条记录应包括函数名及功能简要说明

/// 1. ....

 /// \History: 修改历史记录列表，每条修改记录应包括修改日期、修改者及修改内容简述

///

/// Hsz 2005/4/12 1.0 build this moudle

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

函数头部注释规范，列出：函数的目的/功能、输入参数、输出参数、返回值、调用关系（函数、表）等。示例：下面这段函数的注释比较标准，当然，并不局限于此格式，但上述信息建议要包含在内：

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

///  \fn    函数名称

/// \brief 函数功能、性能等的描述.

/// \param[in] 参数 c a char.

/// \param[out] 参数        n an int.

/// \exception 异常 std::out_of_range parameter is out of range.

/// \return 返回值 a char pointer.

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

类的头部注释规范：

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

/// \class 类名字 类所在文件 "文件路径"

/// \brief 大纲描述.

///

/// 详细描述类的功能

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

类成员定义的注释规范：

成员函数

/// A function.

/// A more elaborate description of the constructor.

成员变量

///< a public variable. Details

标准类型的注释规范：

Enum

第一种方法

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

/// \enum TEnum

/// A description of the enum type.

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

enum TEnum {

                Val1, /// \var Enum Val1

                Val2 ///      Enum Val2

};

第二种方法

enum在类内部定义

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

/// \enum 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.

#define macro宏定义

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

/// \def MAX(x,y)

/// Computes the maximum of \a x and \a y.

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

typedef类型定义

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

/// \typedef std::string YString

/// typedef YString.

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

Struct结构

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

/// \struct Test struct.h "inc/ struct.h"

/// \brief This is a test struct.

/// Some details about the Test struct

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

变量定义

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

/// \var int g_nCount

/// The description of the int value.

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

您可依照此规定在你自己的程序代码中加上对应的注释。其实，无论你有没有使用Doxygen ，

都不妨按照他的格式將注释写入，一方面是依照他的格式，並不会甘于您程序的运行。

另一方面，Doxygen 所定义的都是基本程序注释应当要的东西。

如果您使用Doxygen Wizard，可直接使用上面的Run 的按鈕或选项來制作说明文件。

如果是生产HTML文件，在HTML_OUTPUT 所指定的目录中的index.html將是您说明文件的首页。