I've written C code containing a state machine 1. Now I'm looking for a way to generate a html file documenting that state machine like [2].
I've looked at doxygen [3]. It can extract texts, callgraphs and the like, but it cannot generate state machine diagrams. I've looked at Graphviz [4]. It can generate state machine graphs, but it cannot combine text and the graph in one html file. I've found a Doxygen Preprocessor [5], that claims to be able to document state machines, but the last update is from 2009
Does anybody know a system that can extract both text and diagrams from source code, or specially crafted comments in the code, and that is actively developed?
Edit 1 I've not expressed my question as clearly as I should have. I would like to figure out a workflow that enables me to document and verify the C code I make for a product based on a microcontroller.
I would like to enable my users with limited to no programming knowledge to be able to understand what I'm about to implement in C code, so there's a higher chance that the C code I make is actually what the user wants.
So far I came up with this workflow:
1) Me and the user sit down, and discuss what all the fault conditions are that can happen, and what my program should do in response to those. This is stored in a spreadsheet.
2) I convert the spreadsheet from step 1 into one or more state machines. This can be done by pen and paper. When this is done, I let the user check if the state machine is consistent with the spreadsheet.
3) I write the state machine in machine understandable form, and let a program generate the graphical representation of the state machine. I let the user check if this is the same state machine as the version of step 2.
4) I take the machine understandable form of the state machine, and use that to write unit tests for each state and transition of the state machine. I let a co-worker with programming skills check if the unit tests are consistent with the state machine.
5) I write the C code, and tweak it so that it passes all the unit tests.
6) The finished product is tested according to the scenario's from step 1.
While writing this down, I realize there's a lot of manual work in this process that may be done automatically. Do you know of tools that can do this?
SMC [6] as suggested by Fiddling Bits looks promising, but I'm unsure if it can generate a C-file like the one posted under 1. I'm also unsure if I can do a round trip like this: I write the state machine in a .sm file, let SMC generate a C file. I edit the C file, I let SMC update the .sm file, I edit the .sm file, and let SMC update the C file again.
Edit 2 I've looked at plantuml as suggested by Marc, but that adds extra complexity in the tools needed to generate the html pages.
I've solved the problem by using the \dot command [7] to embed a graphvid diagram in an doxygen command block. See [8] for the C code.
1 the C code
typedef enum
{
stIDLE=0,
stDONE
} TRXSTATES;
TRXSTATES theState = stIDLE;
void execute (void)
{
switch (theState)
{
case stIDLE:
{
theState = stDONE
break;
}
case stDONE:
{
break;
}
}
}
[2] the desired html page
Some smart text about this state machine
+--------+ +--------+
+ stIDLE + ----> + stDONE +
+--------+ +--------+
[3] http://www.doxygen.nl/index.html
[5] https://sites.google.com/site/abudden/doxygen-preprocessor
[6] http://smc.sourceforge.net/
[7] http://www.doxygen.nl/manual/commands.html#cmddot
[8] the updated C code
/** \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;
}
}
}
