c - 包含状态机的文档 C 代码

Question

我编写了包含状态机的 C 代码 1 .现在我正在寻找一种方法来生成一个 html 文件来记录该状态机，例如 [2]。

我看过 doxygen [3]。它可以提取文本、调用图等，但不能生成状态机图。
我看过 Graphviz [4]。它可以生成状态机图，但不能将文本和图合并到一个 html 文件中。
我发现了一个 Doxygen Preprocessor [5]，它声称能够记录状态机，但最后一次更新是从 2009 年开始的

有谁知道一个系统可以从源代码中提取文本和图表，或者代码中特制的注释，并且正在积极开发中？

编辑 1
我没有像我应该的那样清楚地表达我的问题。我想找出一个工作流程，使我能够记录和验证我为基于微 Controller 的产品制作的 C 代码。

我想让我的用户几乎没有编程知识，能够理解我将要在 C 代码中实现的内容，因此我编写的 C 代码更有可能是用户想要的。

到目前为止，我想出了这个工作流程:

1) 我和用户坐下来，讨论所有可能发生的故障情况，以及我的程序应该如何应对这些情况。这存储在电子表格中。

2) 我将步骤 1 中的电子表格转换为一个或多个状态机。这可以通过笔和纸来完成。完成后，我让用户检查状态机是否与电子表格一致。

3)我以机器可理解的形式编写状态机，并让程序生成状态机的图形表示。我让用户检查这是否与步骤 2 的版本相同。

4)我采用状态机的机器可理解形式，并使用它为状态机的每个状态和转换编写单元测试。我让一个有编程技能的同事检查单元测试是否与状态机一致。

5) 我编写了 C 代码，并对其进行了调整，使其通过了所有单元测试。

6) 根据步骤 1 中的场景对成品进行测试。

写下来时，我意识到在这个过程中有很多可以自动完成的手动工作。您知道可以执行此操作的工具吗？

Fddling Bits 建议的 SMC [6] 看起来很有希望，但我不确定它是否可以生成一个 C 文件，就像在 1 下发布的一样。 .我也不确定我是否可以做这样的往返:我在 .sm 文件中编写状态机，让 SMC 生成一个 C 文件。我编辑 C 文件，让 SMC 更新 .sm 文件，编辑 .sm 文件，然后让 SMC 再次更新 C 文件。

编辑 2
我已经按照 Marc 的建议查看了 plantuml，但这增加了生成 html 页面所需工具的额外复杂性。

我已经通过使用\dot 命令 [7] 在 doxygen 命令块中嵌入 graphvid 图解决了这个问题。有关 C 代码，请参见 [8]。

1 C 代码

typedef enum
{
    stIDLE=0,
    stDONE
} TRXSTATES;

TRXSTATES theState = stIDLE;

void execute (void)
{
    switch (theState)
    {
        case stIDLE:
        {
            theState = stDONE
            break;
        }
        case stDONE:
        {
            break;
        }
    }
}

[2] 想要的html页面

Some smart text about this state machine
+--------+       +--------+
+ stIDLE + ----> + stDONE +
+--------+       +--------+

[3] http://www.doxygen.nl/index.html

[4] http://graphviz.org/

[5] https://sites.google.com/site/abudden/doxygen-preprocessor

[6] http://smc.sourceforge.net/

[7] http://www.doxygen.nl/manual/commands.html#cmddot

[8] 更新的 C 代码

/** \mainpage
 * Some smart text about this state machine
 * \dot
 * digraph statemachine {
 *      rankdir=LR
 *      node [shape=record, fontname=Helvetica, fontsize=10];
 *      stIdle [ label="Idle" ];
 *      stDone [ label="Done" ];
 *      stIdle -> stDone [ label ="Finished", arrowhead="open", style="solid" ];
 *  }
 *  \enddot
*/
typedef enum
{
    stIDLE=0,
    stDONE
} TRXSTATES;

TRXSTATES theState = stIDLE;

void execute (void)
{
    switch (theState)
    {
        case stIDLE:
        {
            theState = stDONE
            break;
        }
        case stDONE:
        {
            break;
        }
    }
}  

Answer 1

一种可能的方法是使用 plantuml以文本形式编码图表，在 doxygen .

图表示例:

https://dev.mysql.com/doc/dev/mysql-server/latest/structpfs__lock.html

源码，看@startuml/@enduml
https://github.com/mysql/mysql-server/blob/8.0/storage/perfschema/pfs_lock.h

这些图表是手动维护的，这也允许在生成的文档中添加注释、评论等。