如何在Doxygen中创建状态图？

Question

我想使用Doxygen生成状态图，是否有什么诀窍可以帮助我们实现这个目标？

目前我只是使用预格式化的文本，然后添加自己的“自由文本图表”，但这很难维护并且需要耗费时间来绘制。

我使用Doxygen生成的所有其他图表（例如继承、关系等），但由于状态机不是“标准”的C/C++结构（即每个设计者可以以不同的方式实现它们），我想没有自动的方法告诉Doxygen为您完成此操作。 但是，是否有一种创建可以在每个状态旁边进行注释的图表元素的方法呢？也许像这个简陋的例子一样：

\section state Diagram
... description

\state state1...
\value1 returns state2
\value2 returns state1
int myState1Handler(){...}

\state state2...
\value1 returns state1
\value2 returns state2
int myState2Handler(){...}

编辑1：

或者，是否可能像下面评论中建议的那样使用graphviz标记语言，并以某种方式将它们与doxygen输出集成起来？

- code_fodder

---

也许有可能以某种方式直接从一些额外的源控制graphviz输出。 - πάντα ῥεῖ

@g-makulik 听起来很复杂: o，但我会看一下关于graphviz的。 - code_fodder

@g-makulik 哇，实际上graphviz看起来很容易生成状态图（和其他类似的图表）。但我不知道如何将一些graphviz标记代码插入到我的代码文件中，然后将其输出到doxygen...我猜这就是你所说的“控制graphviz输出”的意思...有用的graphviz示例链接 - code_fodder

@g-makulik 哦，好的，真糟糕 :) 我会把这个作为问题的一部分并进行调查，谢谢。 - code_fodder

请查看Doxygen的\dot和\dotfile命令。 - albert

Answer 1

Doxygen（至少是最新版本）提供了\dotfile和\dot特殊命令，以插入任意的.dot文件或内联dot图形描述，以在生成的文档中使用graphviz进行呈现。

您还可以考虑使用类似于SMC的工具来管理状态机（通过建模、可视化表示和代码生成）。

- πάντα ῥεῖ

---

谢谢，我会试一下！SMC看起来也很棒 :) - code_fodder

Answer 2

使用dot脚本语言，将脚本放在\dot和\enddot之间，即可在doxygen中添加自定义图形。

我在我的cpp代码中测试了这个例子，使用doxygen效果非常好:

/*! 
   Class relations expressed via an inline dot graph:
   \dot
   digraph example {
       node [shape=record, fontname=Helvetica, fontsize=10];
       b [ label="class B" URL="\ref B"];
       c [ label="class C" URL="\ref C"];
       b -> c [ arrowhead="open", style="dashed" ];
   }
   \enddot
   Note that the classes in the above graph are clickable
   (in the HTML output).
 */

void main()
{
  //write some code here...
}

结果：

要查看更多dot图脚本示例，请参阅以下来源：

1. https://edotor.net/ - 它实际上向您展示了一些示例，您可以更改它们并立即在右侧看到结果。
2. http://msc-generator.sourceforge.net/help/5.4/Graph-Language-Tutorial.html - 不错的例子
3. https://graphviz.org/documentation/ - dot语言的完整文档，供那些想深入了解的人使用。

- Eyal Gerber

---

以上的链接非常好，谢谢。您是msc-generator的作者吗？在第二个链接中，我看到左侧点的代码是以图像格式呈现的，我建议将其更改为文本格式，这样我们就可以简单地复制和粘贴了。 - ollydbg23

@ollydbg23 我不是 msc-generator 的作者。但我同意你的推荐 :) - Eyal Gerber

Answer 3

我想在这个问题中添加plantuml。这是一个基于文本的uml图生成器。它的好处在于可以生成运行时输出（状态图、序列图等）。

例如，每次状态转换时，您都可以将一个plantuml格式的行打印到文件中。当程序终止时（或任何时间），您可以在输出文件上运行plantuml（可能需要添加开始/结束标记-微不足道），然后您就会得到一个uml图！...自那以后，我已经在3个不同的项目上使用了它-主要用于序列图。

好吧，这并不是真正的“离线”设计文档，在某些方面它更好，因为您可以获得自我记录的代码，即生成的图表正是代码正在执行的操作。这里是一个非常简单的plantuml序列图示例：

@startuml
component1 -> component2 : helloMsg
component2 -> component1 : replyMsg
@enduml

如果这是您的程序输出结果，则：

java -jar <path-to-plantuml.jar>/plantuml.jar myoutput.log

这将生成：myoutput.png（图像）。plantuml.jar可在plantuml网站上免费下载...免费而简单！

- code_fodder

---

Doxygen支持在此答案中所述的PlantUML命令，并将其自动转换为图像。请参阅Doxygen文档（有关startuml段落和有关配置选项PLANTUML_...的部分）。 - albert

@Caleth 我知道 - 我是原帖作者...但那个工具对我来说真的很有用。 - code_fodder

@albert - 哦，太酷了！- 更好的是，我不知道Doxygen支持plantuml：） - code_fodder

@Caleth，这不是Java示例 - 这也适用于C ++或任何可以生成基于文件的输出（即日志文件）的语言。 Plantuml使用Java将输出文本文件处理为UML图。 - code_fodder