0. 简介
在提升算法认识的同时，本人逐渐认识到有一个好的开发文档/UML图是多么方便，而很多时候代码的开发维护总是会缺少这样的工作。这里以Doxygen为主，介绍本人在Ubuntu环境下的开发操作。
1. Doxygen安装
Ubuntu/Debian安装
sudo apt-get install doxygen
生成配置文件
doxygen -g
该命令会在当前路径生成一个名为Doxyfile配置文件。这里可以考虑使用第三点的文件直接输出一个合适的Doxygen文档。
2. Doxygen设置vscode配置文件
- 选择安装扩展：左下角齿轮，扩展，搜索“doxdocgen”
- 安装后，左侧插件上点邮件，菜单中选“扩展设置”
- 点击“在setting.json编辑”，直接打开setting.json文件，贴上下述代码。
{
"editor.tabSize": 2,
"editor.rulers": [
100
],
"editor.fontSize": 16,
"emmet.excludeLanguages": [
"markdown"
],
// vscode默认启用了根据文件类型自动设置tabsize的选项
"editor.detectIndentation": true,
// // 重新设定tabsize
"editor.tabSize": 2,
// #每次保存的时候自动格式化
"editor.formatOnSave": true,
"editor.formatOnSaveMode": "modifications",
// "editor.defaultFormatter": "xaver.clang-format",
"C_Cpp.clang_format_fallbackStyle": "{ BasedOnStyle: LLVM, UseTab: Never, IndentWidth: 4, TabWidth: 4,}",
"C_Cpp.clang_format_style": "{ BasedOnStyle: LLVM, UseTab: Never, IndentWidth: 4, TabWidth: 4, }",
"[cpp]": {
"editor.defaultFormatter": "ms-vscode.cpptools"
},
"C_Cpp.formatting": "Default",
"C_Cpp.vcFormat.indent.accessSpecifiers": true,
"clang-format.fallbackStyle": "Google",
"files.associations": {
"*.repos": "yaml",
"*.world": "xml",
"*.xacro": "xml",
"chrono": "cpp",
"*.ipp": "cpp",
"*.h": "cpp",
"bitset": "cpp",
"memory": "cpp",
"random": "cpp",
"future": "cpp",
"optional": "cpp",
"ostream": "cpp",
"iostream": "cpp",
"cctype": "cpp",
"clocale": "cpp",
"cmath": "cpp",
"csignal": "cpp",
"cstdarg": "cpp",
"cstddef": "cpp",
"cstdio": "cpp",
"cstdlib": "cpp",
"cstring": "cpp",
"ctime": "cpp",
"cwchar": "cpp",
"cwctype": "cpp",
"array": "cpp",
"atomic": "cpp",
"strstream": "cpp",
"bit": "cpp",
"*.tcc": "cpp",
"codecvt": "cpp",
"complex": "cpp",
"condition_variable": "cpp",
"cstdint": "cpp",
"deque": "cpp",
"list": "cpp",
"map": "cpp",
"set": "cpp",
"unordered_map": "cpp",
"vector": "cpp",
"exception": "cpp",
"algorithm": "cpp",
"functional": "cpp",
"iterator": "cpp",
"memory_resource": "cpp",
"numeric": "cpp",
"ratio": "cpp",
"regex": "cpp",
"string": "cpp",
"string_view": "cpp",
"system_error": "cpp",
"tuple": "cpp",
"type_traits": "cpp",
"utility": "cpp",
"fstream": "cpp",
"initializer_list": "cpp",
"iomanip": "cpp",
"iosfwd": "cpp",
"istream": "cpp",
"limits": "cpp",
"mutex": "cpp",
"new": "cpp",
"shared_mutex": "cpp",
"sstream": "cpp",
"stdexcept": "cpp",
"streambuf": "cpp",
"thread": "cpp",
"cfenv": "cpp",
"cinttypes": "cpp",
"typeindex": "cpp",
"typeinfo": "cpp",
"valarray": "cpp",
"variant": "cpp",
"core": "cpp",
"queue": "cpp",
"unordered_set": "cpp",
"dense": "cpp",
"numericaldiff": "cpp",
"*.idl": "cpp",
"any": "cpp",
"hash_map": "cpp",
"hash_set": "cpp",
"ceres.h": "c",
"se3.hpp": "c",
"rotation.h": "c"
},
// Autocomplete from ros python packages
"python.autoComplete.extraPaths": [
"/opt/ros/foxy/lib/python3.8/site-packages/"
],
// Environment file lets vscode find python files within workspace
"python.envFile": "${workspaceFolder}/.env",
// Use the system installed version of autopep8
"python.formatting.autopep8Path": "/usr/bin/autopep8",
"python.formatting.autopep8Args": [
"--max-line-length=100"
],
"C_Cpp.default.intelliSenseMode": "clang-x64",
"C_Cpp.formatting": "Disabled",
"uncrustify.useReplaceOption": true,
"uncrustify.configPath.linux": "/opt/ros/foxy/lib/python3.8/site-packages/ament_uncrustify/configuration/ament_code_style.cfg",
"cSpell.words": [
"athackst",
"autopep",
"cmake",
"cppcheck",
"cpplint",
"deque",
"devcontainer",
"ints",
"noqa",
"odometry",
"pytest",
"rclcpp",
"rclpy",
"repos",
"rosdistro",
"rosidl",
"RTPS",
"uncrustify",
"xmllint"
],
"search.exclude": {
"**/node_modules": true,
"**/bower_components": true,
"**/*.code-search": true,
"**/build": true,
"**/install": true,
"**/log": true
},
"python.analysis.extraPaths": [
"/opt/ros/foxy/lib/python3.8/site-packages/"
],
"cSpell.allowCompoundWords": true,
"cSpell.ignorePaths": [
"**/package-lock.json",
"**/node_modules/**",
"**/vscode-extension/**",
"**/.git/objects/**",
".vscode",
".vscode-insiders",
".devcontainer/devcontainer.json"
],
"ros.distro": "foxy",
"C_Cpp.errorSquiggles": "Disabled",
// Doxygen documentation generator set
// 文件注释：版权信息模板
"doxdocgen.file.copyrightTag": [
"@copyright Copyright (c) {year} TEST"
],
// 文件注释：自定义模块，这里我添加一个修改日志
"doxdocgen.file.customTag": [
"@par 修改日志:",
"<table>",
"<tr><th>Date <th>Version <th>Author <th>Description",
"<tr><td>{date} <td>2.0 <td>test <td>内容",
"</table>",
],
// 文件注释的组成及其排序
"doxdocgen.file.fileOrder": [
"file", // @file
"brief", // @brief 简介
"author", // 作者
"version", // 版本
"date", // 日期
"empty", // 空行
"copyright",// 版权
"empty",
"custom" // 自定义
],
// 下面时设置上面标签tag的具体信息
"doxdocgen.file.fileTemplate": "@file {name}",
"doxdocgen.file.versionTag": "@version 2.0",
"doxdocgen.generic.authorEmail": "test@test.com",
"doxdocgen.generic.authorName": "test",
"doxdocgen.generic.authorTag": "@author {author} ({email})",
// 日期格式与模板
"doxdocgen.generic.dateFormat": "YYYY-MM-DD",
"doxdocgen.generic.dateTemplate": "@date {date}",
// 根据自动生成的注释模板（目前主要体现在函数注释上）
"doxdocgen.generic.order": [
"brief",
"tparam",
"param",
"return"
],
"doxdocgen.generic.paramTemplate": "@param{indent:8}{param}{indent:25}My Param doc",
"doxdocgen.generic.returnTemplate": "@return {type} ",
"doxdocgen.generic.splitCasingSmartText": true,
"cmake.sourceDirectory": "${workspaceFolder}/src/test",
}
3. Doxygen设置Doxyfile
模板Doxyfile，可以根据需要更改相应设置，下面是一个较为完整的Doxyfile配置文件，可以直接替换。
DOXYFILE_ENCODING = UTF-8
# 项目名称，将作为于所生成的程序文档首页标题
PROJECT_NAME = "Project"
# 文档版本号，可对应于项目版本号，譬如 svn、cvs 所生成的项目版本号
PROJECT_NUMBER = 1.0.0
CREATE_SUBDIRS = NO
ALLOW_UNICODE_NAMES = NO
# 程序文档语言环境
OUTPUT_LANGUAGE = English
OUTPUT_TEXT_DIRECTION = None
BRIEF_MEMBER_DESC = YES
REPEAT_BRIEF = YES
ABBREVIATE_BRIEF = "The $name class" \
"The $name widget" \
"The $name file" \
is \
provides \
specifies \
contains \
represents \
a \
an \
the
ALWAYS_DETAILED_SEC = NO
INLINE_INHERITED_MEMB = NO
FULL_PATH_NAMES = YES
SHORT_NAMES = NO
JAVADOC_AUTOBRIEF = NO
JAVADOC_BANNER = NO
QT_AUTOBRIEF = NO
MULTILINE_CPP_IS_BRIEF = NO
INHERIT_DOCS = YES
SEPARATE_MEMBER_PAGES = NO
TAB_SIZE = 4
# 如果是制作 C 程序文档，该选项必须设为 YES，否则默认生成 C++ 文档格式
OPTIMIZE_OUTPUT_FOR_C = NO
OPTIMIZE_OUTPUT_JAVA = NO
OPTIMIZE_FOR_FORTRAN = NO
OPTIMIZE_OUTPUT_VHDL = NO
OPTIMIZE_OUTPUT_SLICE = NO
MARKDOWN_SUPPORT = YES
TOC_INCLUDE_HEADINGS = 5
AUTOLINK_SUPPORT = YES
BUILTIN_STL_SUPPORT = NO
CPP_CLI_SUPPORT = NO
SIP_SUPPORT = NO
IDL_PROPERTY_SUPPORT = YES
DISTRIBUTE_GROUP_DOC = NO
GROUP_NESTED_COMPOUNDS = NO
SUBGROUPING = YES
INLINE_GROUPED_CLASSES = NO
INLINE_SIMPLE_STRUCTS = NO
# 对于使用 typedef 定义的结构体、枚举、联合等数据类型，只按照 typedef 定义的类型名进行文档化
TYPEDEF_HIDES_STRUCT = NO
LOOKUP_CACHE_SIZE = 0
EXTRACT_ALL = NO
EXTRACT_PRIVATE = NO
EXTRACT_PRIV_VIRTUAL = NO
EXTRACT_PACKAGE = NO
EXTRACT_STATIC = NO
EXTRACT_LOCAL_CLASSES = YES
EXTRACT_LOCAL_METHODS = NO
EXTRACT_ANON_NSPACES = NO
HIDE_UNDOC_MEMBERS = NO
HIDE_UNDOC_CLASSES = NO
HIDE_FRIEND_COMPOUNDS = NO
HIDE_IN_BODY_DOCS = NO
INTERNAL_DOCS = NO
CASE_SENSE_NAMES = YES
# 在 C++ 程序文档中，该值可以设置为 NO，而在 C 程序文档中，由于 C 语言没有所谓的域/名字空间这样的概念，所以此处设置为 YES
HIDE_SCOPE_NAMES = NO
HIDE_COMPOUND_REFERENCE= NO
SHOW_INCLUDE_FILES = YES
SHOW_GROUPED_MEMB_INC = NO
FORCE_LOCAL_INCLUDES = NO
INLINE_INFO = YES
SORT_MEMBER_DOCS = YES
SORT_BRIEF_DOCS = NO
SORT_MEMBERS_CTORS_1ST = NO
SORT_GROUP_NAMES = NO
SORT_BY_SCOPE_NAME = NO
STRICT_PROTO_MATCHING = NO
GENERATE_TODOLIST = YES
GENERATE_TESTLIST = YES
GENERATE_BUGLIST = YES
GENERATE_DEPRECATEDLIST= YES
MAX_INITIALIZER_LINES = 30
SHOW_USED_FILES = YES
SHOW_FILES = YES
SHOW_NAMESPACES = YES
# 让 doxygen 静悄悄地为你生成文档，只有出现警告或错误时，才在终端输出提示信息
QUIET = YES
WARNINGS = YES
WARN_IF_UNDOCUMENTED = YES
WARN_IF_DOC_ERROR = YES
WARN_NO_PARAMDOC = NO
WARN_AS_ERROR = NO
WARN_FORMAT = "$file:$line: $text"
INPUT_ENCODING = UTF-8
# 只对头文件中的文档化信息生成程序文档
FILE_PATTERNS = *.c \
*.cc \
*.cxx \
*.cpp \
*.c++ \
*.h \
*.hh \
*.hxx \
*.hpp \
*.h++ \
# 递归遍历当前目录的子目录，寻找被文档化的程序源文件
RECURSIVE = YES
EXCLUDE_SYMLINKS = NO
EXAMPLE_PATTERNS = *
EXAMPLE_RECURSIVE = NO
FILTER_SOURCE_FILES = NO
SOURCE_BROWSER = NO
INLINE_SOURCES = NO
STRIP_CODE_COMMENTS = YES
# 允许程序文档中显示本文档化的函数相互调用关系
REFERENCED_BY_RELATION = YES
REFERENCES_RELATION = YES
REFERENCES_LINK_SOURCE = YES
SOURCE_TOOLTIPS = YES
USE_HTAGS = NO
VERBATIM_HEADERS = YES
CLANG_ASSISTED_PARSING = NO
ALPHABETICAL_INDEX = YES
COLS_IN_ALPHA_INDEX = 5
# 生成 html 格式的程序文档
GENERATE_HTML = YES
HTML_OUTPUT = html
HTML_FILE_EXTENSION = .html
HTML_COLORSTYLE_HUE = 220
HTML_COLORSTYLE_SAT = 100
HTML_COLORSTYLE_GAMMA = 80
HTML_TIMESTAMP = NO
HTML_DYNAMIC_MENUS = YES
HTML_DYNAMIC_SECTIONS = NO
HTML_INDEX_NUM_ENTRIES = 100
GENERATE_DOCSET = NO
DOCSET_FEEDNAME = "Doxygen generated docs"
DOCSET_BUNDLE_ID = org.doxygen.Project
DOCSET_PUBLISHER_ID = org.doxygen.Publisher
DOCSET_PUBLISHER_NAME = Publisher
GENERATE_HTMLHELP = NO
CHM_FILE =
HHC_LOCATION =
GENERATE_CHI = NO
BINARY_TOC = NO
TOC_EXPAND = NO
GENERATE_QHP = NO
QHP_NAMESPACE = org.doxygen.Project
QHP_VIRTUAL_FOLDER = doc
GENERATE_ECLIPSEHELP = NO
ECLIPSE_DOC_ID = org.doxygen.Project
DISABLE_INDEX = NO
#这会在HTML文档中，添加一个侧边栏，并以树状结构显示包、类、接口等的关系
GENERATE_TREEVIEW = YES
ENUM_VALUES_PER_LINE = 4
TREEVIEW_WIDTH = 250
EXT_LINKS_IN_WINDOW = NO
FORMULA_FONTSIZE = 10
FORMULA_TRANSPARENT = YES
USE_MATHJAX = NO
MATHJAX_FORMAT = HTML-CSS
MATHJAX_RELPATH = https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/
SEARCHENGINE = YES
SERVER_BASED_SEARCH = NO
EXTERNAL_SEARCH = NO
SEARCHDATA_FILE = searchdata.xml
# 生成 latex 格式的程序文档
GENERATE_LATEX = NO
LATEX_OUTPUT = latex
MAKEINDEX_CMD_NAME = makeindex
LATEX_MAKEINDEX_CMD = makeindex
COMPACT_LATEX = NO
PAPER_TYPE = a4
PDF_HYPERLINKS = YES
USE_PDFLATEX = YES
LATEX_BATCHMODE = NO
LATEX_HIDE_INDICES = NO
LATEX_SOURCE_CODE = NO
LATEX_BIB_STYLE = plain
LATEX_TIMESTAMP = NO
GENERATE_RTF = NO
RTF_OUTPUT = rtf
COMPACT_RTF = NO
RTF_HYPERLINKS = NO
RTF_SOURCE_CODE = NO
GENERATE_MAN = NO
MAN_OUTPUT = man
MAN_EXTENSION = .3
MAN_LINKS = NO
GENERATE_XML = NO
XML_OUTPUT = xml
XML_PROGRAMLISTING = YES
XML_NS_MEMB_FILE_SCOPE = NO
GENERATE_DOCBOOK = NO
DOCBOOK_OUTPUT = docbook
DOCBOOK_PROGRAMLISTING = NO
GENERATE_AUTOGEN_DEF = NO
GENERATE_PERLMOD = NO
PERLMOD_LATEX = NO
PERLMOD_PRETTY = YES
ENABLE_PREPROCESSING = YES
MACRO_EXPANSION = NO
EXPAND_ONLY_PREDEF = NO
SEARCH_INCLUDES = YES
SKIP_FUNCTION_MACROS = YES
ALLEXTERNALS = NO
EXTERNAL_GROUPS = YES
EXTERNAL_PAGES = YES
CLASS_DIAGRAMS = YES
HIDE_UNDOC_RELATIONS = YES
# 在程序文档中允许以图例形式显示函数调用关系，前提是你已经安装了 graphviz 软件包
HAVE_DOT = YES
DOT_NUM_THREADS = 0
DOT_FONTNAME = Helvetica
DOT_FONTSIZE = 10
CLASS_GRAPH = YES
LLABORATION_GRAPH = YES
GROUP_GRAPHS = YES
UML_LOOK = NO
UML_LIMIT_NUM_FIELDS = 10
TEMPLATE_RELATIONS = NO
INCLUDE_GRAPH = YES
INCLUDED_BY_GRAPH = YES
CALL_GRAPH = NO
CALLER_GRAPH = YES
GRAPHICAL_HIERARCHY = YES
DIRECTORY_GRAPH = YES
DOT_IMAGE_FORMAT = png
INTERACTIVE_SVG = NO
DOT_GRAPH_MAX_NODES = 50
MAX_DOT_GRAPH_DEPTH = 0
DOT_TRANSPARENT = NO
DOT_MULTI_TARGETS = NO
GENERATE_LEGEND = YES
DOT_CLEANUP = YES
4. 可视化输出Doxygen GUI
Ubuntu/Debian安装
sudo apt-get install doxygen-gui
然后打开gui界面
doxywizard
主要需要填写的内容如下图：
同样可以生成Doxygen文档以及UML图
5. 参考链接
https://blog.csdn.net/zhonglinliu/article/details/78604397
https://blog.csdn.net/robinfoxnan/article/details/121420821
https://blog.csdn.net/Q1302182594/article/details/51517880
评论（0）
您还未登录，请登录后发表或查看评论