CLion教程-Doxygen 文档

Doxygen 风格的注释可以分布在源代码中,并用于生成各种格式的完整文档。如果您的项目是以这种方式进行文档编写的,您可以轻松地从 CLion 的内置终端中运行 Doxygen 工具以获取文档。此外,CLion 还可以在 IDE 内部为 Doxygen 注释提供更多价值。
CLion 将 Doxygen 风格的注释信息包含在快速文档弹出窗口 Ctrl0Q 中:
查看 Doxygen 文档
Doxygen 风格的信息包含在快速文档弹出窗口中,除了类型信息。要调用文档弹出窗口:
- 将插入符号放置在所需的符号位置或 Doxygen 注释的
@param
命令处。 - 按下 Ctrl+Q。
或者,当选中复选框 Show quick documentation on hover (CLion | Settings | Editor | General | Other) 时,只需将鼠标指针移到所需的符号上方。
如果函数参数在函数描述之外单独进行文档编写,CLion 将合并所有注释,并显示完整函数的签名文档(与 Doxygen 在生成输出时的方式相同):
创建 Doxygen 注释
要从头开始创建 Doxygen 注释:
- 输入以下符号之一:
///
、//!
、/**
或/*!
,然后按 Enter 键。 - 您将获得一个填充文档文本的存根:
要更改前缀类型或添加 @brief
标记:
- 转到 Settings | Editor | Code Style | C/C++。
- 打开 Code Generation 选项卡,并向下滚动到 Documentation Comments 部分:
可靠的重命名
在重命名函数或其参数时,Doxygen 注释需要相应地更新。在 重命名 重构 ShiftF6 时,CLion 会随着其他引用一起更新 Doxygen 注释。
之前:
之后:
输入辅助
CLion 的 自动完成 功能提供了基本的 Doxygen 命令 输入辅助:
请注意,并非所有命令都在自动完成中可用。
渲染的 Doxygen 注释视图
在 CLion 中,Doxygen 注释可以以更易读的格式显示。在此渲染视图模式中,项目按标记分组显示,而标记本身则被省略。
请注意渲染视图的限制:
- 无法打开引用的 Web 页面。
- 仅在 EOL 块注释的行首渲染。
切换和配置渲染的视图
- 要进入渲染的视图模式,将鼠标指针悬停在注释上,然后单击标尺中的
,或按下 CtrlAlt+Q。图标会变成
。
- 要退出渲染的视图模式,请在标尺中单击
,或从 Doxygen 注释的上下文菜单中选择 Toggle Rendered View,或按下 CtrlAlt+Q。
- 要为当前文件中的所有 Doxygen 注释启用渲染的视图模式,请在标尺的上下文菜单中选择 Render All Doc Comments。
- 如果需要,选择 Adjust Font Size 从上下文菜单中,并使用滑块更改字体大小。
- 要默认显示所有渲染的 Doxygen 注释,请打开设置对话框(CtrlAlt+S),转到 Editor | General | Appearance,然后选中 Render documentation comments 复选框。
- 要隐藏渲染的视图标尺图标,请在标尺的上下文菜单中选择 Configure Gutter Icons,然后在打开的设置页面上清除 Documentation comments in-place rendering 复选框。
Doxygen 注释颜色
要配置 Doxygen 注释中使用的颜色,请转到 Settings | Editor | Color Scheme | C/C++,然后打开 Comments | Doxygen 节点: