MarkdownDoxygen语法规范_markdown define

Markdown 与 Doxygen

一、markdown语法

1. 加粗

---

使用 加粗，而不是 加粗

2. 斜体

使用 斜体，而不是 斜体

3. 加粗并斜体

使用 粗斜，而不是 粗斜 等

4. 链接

段落内使用 google，左右各空一格。不使用 Text，它会使段落看起来臃肿（链接通常都很长）

5. 链接 url 放在哪？

比如你有这样一个段落：google
紧跟段落后面，还是一大章节后面，还是全文最后？
我的建议是尽量放在章节后。
例如：
我经常去的几个网站 Google baidu

6 使用~~给文字添加删除线

这是一段删除线 这句话被删除了

7 表格

7 引用

这是引用的内容

这是引用的内容

这是引用的内容

8 分割三个或者三个以上的 - 或者 * 都可以。

示例:

9 列表

• 列表内容

• 列表内容
  • 下级列表 加三个空格

• 列表内容

10 代码

单行代码：代码之间分别用一个反引号包起来
代码内容

---

代码块：代码之间分别用三个反引号包起来，且两边的反引号单独占一行

  代码...
  代码...
  代码...
1
2
3

11. 空格、空行、分隔符

通常在 #### 一个小节 前留多个空行，后面加一个空行再开始小节内容。
段落不缩进两个字符。段落之间留一个空行。
在应该分割的地方，Markdown 支持用一个空行加 —（可以更多个-） 形成一个

---

（分割符）。但基于视觉上的考虑我使用整 80 个 -，而不是三个。（还是三个方便，手敲就行，不用依赖 Emacs 之类编辑器。）
中英文之间加空格，用 “汤姆就是 Tom 的音译”，而不是“汤姆就是Tom的音译”。防止专有名词空一格后的割裂感，比起 “我最爱的产品是简书和豆瓣 FM”，我们倾向于使用 “我最爱的产品是简书和豆瓣FM”，或者 “我最爱的产品是 简书 和 豆瓣FM”。

---

12. 单行加长文字

简书笔记是定位于写作者的一款写作软件，界面非常简洁，其最大的特色是支持 Markdown 功能，希望为作者制造出一种沉浸式的写作氛围，进而可以专注于写作。简书还支持写作模式，在简书·笔记中打开写作模式即可让撰写窗全屏化，再配合 Chrome 等浏览器的全屏浏览功能。简书·笔记能够达到与 Q10、MTW 之类的专心致志写作软件同样的效果。
1

二、Doxygen 语法简介

Doxygeny语法简介
Doxygen 是一个程序的文件产生工具，可将程序中的特定批注转换成为说明文件。提供了一套注释方式便于把代码中的注释生成说明文档。下面是常用的注释简介。

1. 简单注释

单行注释：/// 或者//!
多行注释：/** 或者 /*!

2. 文件注释

文件注释通常放在整个文件开头。

/**
 * @file Test.h
 * @brief 测试头文件
 * @details 这个是测试Doxygen
 * @mainpage 工程概览
 * @author sundm75
 * @email sunmd75@163.com
 * @version 1.0.0
 * @date 2019-03-17
 */
1
2
3
4
5
6
7
8
9
10

3. 类定义注释

类定义的注释方式非常简单，使用@brief后面填写类的概述，换号填写类的详细信息。

/**
 * @brief 测试类
 * 主要用来演示Doxygen类的注释方式
 */
 class Test{
 };
1
2
3
4
5
6

4. 常量/变量的注释

常量/变量包括以下几种类型:

• 全局常量变量
• 宏定义
• 类/结构体/联合体的成员变量
• 枚举类型的成员

注释分为两种方式，可根据具体情况自行选择

• 代码前注释

/// 缓存大小
#define BUFSIZ 1024*4
1
2

• 代码后注释

#define BUFSIZ 1024*4 ///< 缓存大小
1

5. 函数注释

• 简约注释
  函数注释主要包含函数简介(@brief)、参数说明(’@param’)、返回说明(@return)和返回值说明(@retval)四部分。

/**
 * @brief 函数简介
 *
 * @param 形参 参数说明
 * @param 形参 参数说明
 * @return 返回说明
 * @retval 返回值说明
 */
1
2
3
4
5
6
7
8

• 详细注释
  可以根据需要添加详细说明(@detail)、注解(@note)、注意(@attention)、警告(@warning)或者异常(@exception)等。

/**
 * @brief 函数简介
 * @detail 详细说明
 * 
 * @param 形参 参数说明
 * @param 形参 参数说明
 * @return 返回说明
 *   @retval 返回值说明
 * @note 注解
 * @attention 注意
 * @warning 警告
 * @exception 异常
 */
1
2
3
4
5
6
7
8
9
10
11
12
13

-例子
以main()函数为例添加函数注释。

/**
* @brief 主函数
* @details 程序唯一入口
*
* @param argc 命令参数个数
* @param argv 命令参数指针数组
* @return 程序执行成功与否
*     @retval 0 程序执行成功
*     @retval 1 程序执行失败
* @note 这里只是一个简单的例子
*/
int main(int argc, char* argv[])
1
2
3
4
5
6
7
8
9
10
11
12

其它

@see
参考

@class
引用类
用于文档生成连接

@var
引用变量
用于文档生成连接

@enum
引用枚举
用于文档生成连接

@code
代码块开始
与@endcode成对使用

@endcode
代码块结束
与@code成对使用

@bug
缺陷
链接到所有缺陷汇总的缺陷列表

@todo
TODO
链接到所有TODO 汇总的TODO 列表

@example
使用例子说明

@remarks
备注说明

@pre
函数前置条件

@deprecated
函数过时说明

Doxygen 使用方法

Doxygen是一个程序的文件产生工具，可将程序中的特定注释转换成为说明文件。而注释基本是对函数、类型和变量的说明。如果能依据程序的结构，将注释经过处理重新整理成为一个纯粹的参考手册，对于后面利用该程序代码的人来说将会减少许多的负担。

---

对于未归档的源文件，也可以通过配置Doxygen来提取代码结构。或者借助自动生成的包含依赖图（includedependency graphs）、继承图（inheritance diagram）以及协作图（collaborationdiagram）来可视化文档之间的关系。Doxygen生成的帮助文档的格式可以是CHM、RTF、PostScript、PDF、HTML和Unixman page等。

---

一个好的程序设计师，在写程序时，都会在适当的地方加上合适的注释。如果，能够在撰写注释时，稍微符合某种格式，接着就可以透过一个工具程序依据程序结构及您的批注产生出漂亮的文件。这将令许多工作繁重的程序设计师有时间多喝几杯咖啡。

---

Doxygen 的使用可分为两大部分。

• 特定格式的批注撰写；
• 利用Doxygen的工具来产生文件。

目前Doxygen可处理的程序语言包含：

• C/C++
• Java
• IDL (Corba, Microsoft及KDE-DCOP类型)
  而可产生出来的文档格式有：
• HTML
• XML
• LaTeX
• RTF
• Unix Man Page

安装

到 Doxygen 的网站上面抓取最新版本的 doxygen，目前较新的 windows 下的版本是doxygen-1.8.15-setup。

使用步骤

• 1）第一次使用需要安装doxygen的程序
• 2）生成doxygen配置文件
• 3）编码时，按照某种格式编写注释
• 4）生成对应文档

配置过程

• Doxygen主页面
• 配置使用的代码格式
• 在Output中，如果需要输出chm格式，勾选chm,否则仅选择html就可以了
• 在 Expert 标签页 ，确定输出的语言，默认是GBK, UTF-8也是比较常用的。
• Build 页面比较重要

Build页面

• 这个页面是生成帮助信息中比较关键的配置页面.
• EXTRACT_ALL 表示：输出所有的函数，但是private和static函数不属于其管制。
• EXTRACT_PRIVATE 表示：输出private函数。
• EXTRACT_STATIC 表示：输出static函数。同时还有几个EXTRACT，相应查看文档即可。
• HIDE_UNDOC_MEMBERS 表示：那些没有使用doxygen格式描述的文档（函数或类等）就不显示了。当然，如果EXTRACT_ALL被启用，那么这个标志其实是被忽略的。
• INTERNAL_DOCS 主要指：是否输出注解中的@internal部分。如果没有被启动，那么注解中所有的@internal部分都
  将在目标帮助中不可见。
• CASE_SENSE_NAMES 表示：是否关注大小写名称，注意，如果开启了，那么所有的名称都将被小写。对于C/C++这种
  字母相关的语言来说，建议永远不要开启。
• HIDE_SCOPE_NAMES 表示：域隐藏，建议永远不要开启。
• SHOW_INCLUDE_FILES 表示：是否显示包含文件，如果开启，帮助中会专门生成一个页面，里面包含所有包含文件的列
  表。
• INLINE_INFO ：如果开启，那么在帮助文档中，inline函数前面会有一个inline修饰词来标明。
• SORT_MEMBER_DOCS ：如果开启，那么在帮助文档列表显示的时候，函数名称会排序，否则按照解释的顺序显
  示。
• GENERATE_TODOLIST ：是否生成TODOLIST页面，如果开启，那么包含在@todo注解中的内容将会单独生成并显
  示在一个页面中，其他的GENERATE选项同。
• SHOW_USED_FILES ：是否在函数或类等的帮助中，最下面显示函数或类的来源文件。
• SHOW_FILES ：是否显示文件列表页面，如果开启，那么帮助中会存在一个一个文件列表索引页面

HTML 项目中的说明

• CHM_FILE文件名需要加上后缀（xx.chm）。
• 如果在 Wizard 的 Output Topics 中选择了 prepare for compressed HTML (.chm)选项，此处就会要求选择 hhc.exe 程序的位置。在 windows help workshop 安装目录下可以找到 hhc.exe。
• 为了解决DoxyGen生成的CHM文件的左边树目录的中文变成了乱码，CHM_INDEX_ENCODING中输入GB2312即可。
• GENERATE_CHI 表示索引文件是否单独输出，建议关闭。否则每次生成两个文件，比较麻烦。
• TOC_EXPAND 表示是否在索引中列举成员名称以及分组（譬如函数，枚举）名称。

运行Doxygen

最后选择RUN标签 运行RUN 点击 Run doxygen 按钮， Doxygen 就会从源代码中抓取符合规范的注释生成你定制的格式的文档。