Doxygen是因代码文档而生，他的特点在于：
- 文档与代码融为一体，注释就是文档
- 代码有变更，注释跟着改，文档也跟着出来
- 文档也可以使用Git版本管理
- 可根据源代码&注释生成漂亮的文档出来，比如常见的html
Doxygen在近期的版本支持了markdown语法，极大简化了一些富文本元素的语法，如标题，列表，表格，图片，链接等等，而且markdown在软件界很流行，经常逛Github, stackoverflow，经常写博客的人运用markdown更加得心应手。
Java有JavaDoc, Python用Sphinx，Ruby用RDoc, 我们C/C++开发者当然用Doxygen.
当然，个人认为Doxygen也有不够好的地方，比如：
- 生成的文档比较凌乱，冗余项很多，不够清晰，简单
- 默认的样式比较丑
- 自定义比较复杂
- 对小型项目/组件/可复用代码不太友好
接下来，后阐述下Doxygen的常见功能和描述我的自定义之路 - 为小型代码打造一个清晰简单的文档。
Getting Start
doxygen文档如何生成，是根据一个配置文件指定的,在这个配置文件指定输入源代码，输出路径，使用的样式表等等。
第一步：生成默认配置文件
$ doxygen -g Doxyfile
第二步：修改配置文件
最主要的是修改输入，输出，其他的属性我们在下文再讲。
INPUT = ../app \
../components \
../doc \
../README.md
RECURSIVE
OUTPUT_DIRECTORY = ../output/doxygen
第三步，生成文档
$ doxygen ./Doxyfile
Documenting the code
Doxygen 官网上写的很详细了，移步这里：
- http://www.stack.nl/~dimitri/doxygen/manual/docblocks.html
- 语法/命令：http://www.stack.nl/~dimitri/doxygen/manual/commands.html
这里，仅仅强调一下group, 善用group可以让文档更有组织，更有条理。
设置group的层次关系
//*****************************************************************************
//
//! \addtogroup HD44780
//! @{
//! \addtogroup HD44780_HelloWorld Hello World
//! @{
//! \addtogroup HD44780_HelloWorld_PutString Put String
//! @{
//
//! @}
//! @}
//! @}
//
//*****************************************************************************
在.md文件中定义group
当需要大篇幅图文文档描述这节的话，可以把这个group拉倒一个 markdown文件中去
Doxygen对markdown也扩展了一些语法，但大体差不多，详细移步： http://www.stack.nl/~dimitri/doxygen/manual/markdown.html
@defgroup HD44780_HelloWorld_PutString Put String @brief An Simple example to show put a sting using the lcd. TODO: 以下是这个Group的详细文档描述，如果需要的话
配置文件
官网：http://www.stack.nl/~dimitri/doxygen/manual/config.html 列出了所有的配置，这里，我挑选了一些经常要改了。
当需要自定义特别的扩展名时
EXTENSION_MAPPING = example=C++
是否安装字母排序Group
SORT_GROUP_NAMES = YES
当需要使用类似C语言的根据#ifdef条件生成不同的文档时，使用
ENABLED_SECTIONS = DOXYGEN_PROJECT
上面的代码用来定义一些条件，这样使用：
@if (DOXYGEN_PROJECT) @defgroup HD44780 @endif
通过一个layout.xml文件自定义布局,比如是否显示Class
LAYOUT_FILE = ./config/layout.xml
如果需要把一个源代码直接插入到一个markdown文档中，那么需要指定Example的根目录
EXAMPLE_PATH = ../
文档中这样插入源代码
@include hd44780_config.h
如果需要把一个.md直接作为首页的话，需指定：
USE_MDFILE_AS_MAINPAGE = ../README.md
自定义Html的头，尾，CSS,
HTML_HEADER = ./assets/include/header.html HTML_FOOTER = ./assets/include/footer.html HTML_EXTRA_STYLESHEET = ./assets/stylesheets/style.css
当不需要生成菜单导航条
DISABLE_INDEX = YES
是否需要生成一个树形的导航
GENERATE_TREEVIEW = YES
告诉doxygen你想声明哪些宏，然后doxygen会根据编译预处理，生成不同的文档 </pre> PREDEFINED = </pre>
自定义输出
首先生成模版，然后自己更改模版
doxygen -w html header.html footer.html style.css
更改CSS
我不太想要Doxygen默认出来的导航，和树形导航，我比较喜欢单页的效果，在加上一个类似 Table of Content的导航
生成后动作
因为多多少少，文档中会有一些图片，附件等等，然后直接是网上的链接也可以，但是我们也可以一起跟代码放在一起，那么文档可能就需要执行一些copy的动作。
这里，我把整个动作写到一个makefile中，通过make来完成这一系列操作。
我的配置
可以移步到我的github项目看：
https://github.com/ahnniu/component-doc-proposal