SLAM拾萃(2)：doxygen

　　今天给大家介绍一下doxygen。这个工具由来已久了，至少08年左右就已经在用了，但是目前还没见到好的介绍。我个人觉得这是个很简单易用的工具，但是为什么看了别人介绍反而觉得复杂了……所以趁着今天比较闲就来说一说它。

---

　　doxygen是一个自动文档生成工具，根据代码里写的注释，自动生成html和latex格式的文档。通常是给c++用的，通常是出html格式的，你看到的pcl网上文档就是拿doxygen生成的。

　　事实上，随意一份代码，都可以拿doxygen生成一个文档，然后在本地看它的代码结构。 我们拿以难读著称的lsd-slam举个例子。

　　首先，建个文件夹，把lsd-slam的代码拷下来：

 git clone https://github.com/tum-vision/lsd_slam.git

　　拷完之后lsd就在你电脑里躺着了。进到package_dir/lsd_slam/lsd_slam_core，打开一看？哇，一堆文件。仔细一看？哇，好多类和变量，还有藏着掖着的全局变量，还有SSE指令！太多了，没法看，怎么办？别急，我们用doxygen生成一个网页来看。网页的好处是可以随处跳转。

---

　　由于你电脑里可能还没有doxygen，我们先来安装一下：

 sudo apt-get install doxygen doxygen-gui

　　什么？你不是Ubuntu怎么办？你都不用Ubuntu了还用我教你装软件？

　　昂，总之，主要是doxygen本体和它的gui模块。我在ubuntu14.04下是这两个包名。如果你不确定，请用apt-cache search doxygen查一下。

　　装好了之后，在该文件夹下开一个doc文件夹，把一会儿生成的文档放里头：

 mkdir doc; cd doc

　　然后，输入doxywizard调出gui面板。

 doxywizard

　　然后就会出一个面板啦，来看看上面都有啥：（外观视你的桌面环境可能略有不同）

　　大概能看出哪些地方要设置吧？首先把Step 1中的目录设到你要保存文档的目录。Project name那些东西随意，可以不设。比较重要的是源代码目录source code directory，请把它设到lsd_slam_core/src下，并钩上Scan recursively，表明我们要扫描子文件夹。然后，输出文件夹设成当前目录./即可，本来我们就在当前目录嘛。

　　这步做好了，点左边的“Mode”，进入下一个版块。下个版块里会让你选语言，既然咱们用c++，保持默认的就可以了。

　　Output和Diagrams也没什么好动的。

　　现在准备工作完成啦！切到Run，点“Run doxygen"，哗啦哗啦，等文档生成完。然后点“show html output"，就可以在浏览器里看到文档啦。如果你下一次想直接看，直接打开doc/html/index.html就可以了！

　　

　　是不是和网上的文档很像啊？看这个比看源代码效果更高哦！

---

命令行

　　doxygen本身是命令行格式的，给一个配置文件，然后根据配置文件去生成文档。但是！几百个配置选项我怎么记得住啊！既然图形界面那么好用为啥要去用命令行啊！哦你没有桌面环境？那还是乖乖用命令行吧……

　　命令行的doxygen也很简单。首先用

 doxygen -s -g settings.txt

　　生成一个配置文件，然后去修改配置文件里的值，基本上和上面讲的差不多啦！只是配置会复杂一点。比较重要的参数有输入，输出，扫描文件的后缀名等等。其实这些都可以在图形界面的“Expert“里配的！我也是这么干的！所以如果你有屏幕的话还是建议你用图形界面啦！当这个文件改好后，调用

doxygen settings.txt

　　按这个文件生成文档。当然如果你写错了，文档就不会生成了！所以还是用图形界面吧！（我在俊哥面前就调了半天这东西的配置文件结果人家妹子都睡着了我才调出来，所以在妹子面前调程序请务必找个熟悉的调）

---

后话

　　doxygen还能按照一些特殊注释格式来生成特别的文档。如果你感兴趣，可以看看上一讲octomap里的那个doc/目录。它也可以用doxygen生成一个文档，但那个文档功能更高级些，可以显示类继承关系树状图等等。据说还能生成别的语言的注释，然而像python估计也不需要这种工具……总之，你要玩的话，doxygen还是有些东西可以玩的，虽然并不太多。本着KISS原则，我还是把它当成一个简单好用的小工具，不必太折腾就能出文档啦！那么，本讲就写到这里，咱们下次再见！