CODEWITHSUNDEEP
c++doxygen
code_fodder
code_fodder

Reputation: 16321

How to create a state diagram in doxygen?

Using doxygen I would like to produce state diagrams somehow. Are there any tricks in doxygen to help us achieve that?

Currently I am just using the pre-formatted text and then adding my own "free-text-diagram" which is hard to maintain and time-consuming to draw out.

I use all of the other diagrams produced by doxygen (i.e. inheritance, relations, etc...) but since state machines are not a "standard" c/c++ construct (i.e. eech designer can implemente them differently) I guess there is no automatic way to tell doxygen to do this for you. But is there some sort of creation of diagram elements that you can comment in next to each state? Maybe somthing like this crude example:

\section state Diagram
... description

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

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

EDIT 1:

Or, is it possible to use the graphviz markup language as suggested in the comments below and integrate them with the doxygen output somehow?

Upvotes: 11

Views: 10181

Answers (3)

Eyal Gerber
Eyal Gerber

Reputation: 1637

You can add your own custom graphs within doxygen using the dot script language and by putting the script between \dot and \enddot

I tested this example myself in my cpp code and it works great with 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...
}

result:

doxygen output with your own custom dot graph

To see more examples of dot graph scripts see the following sources:

  1. https://edotor.net/ - this actually shows you examples and you can change them and see the result immediately on the right.
  2. http://msc-generator.sourceforge.net/help/5.4/Graph-Language-Tutorial.html - nice examples
  3. https://graphviz.org/documentation/ - total documentation of dot language for those who want to go deep.

Upvotes: 3

πάντα ῥεῖ
πάντα ῥεῖ

Reputation: 1

Doxygen (at least the latest version) provides the \dotfile and \dot special commands to insert arbitrary .dot files or inline dot graph descriptions to be rendered with graphviz to the generated documentation.

You might also consider to manage your state machines (by modelling, visual representation and code generation) using a tool like e.g. SMC.

Upvotes: 8

code_fodder
code_fodder

Reputation: 16321

I would like to add plantuml to this question. This is a text-based uml diagram generator. The great thing about it is that you can generate run-time outputs (state diagrams, sequence diagrams, etc...).

For example, each time you state-transition you print a plantuml formatted line to a file. When the programs terminates (or at any time really) you run the plantuml on the output file (may need to add start/end tags - trivial) and you get a uml diagram!... I have since used this on 3 different projects - mostly for sequence diagrams.

Ok so this is not really "offline" design-documentation, in some ways its better because you get self-documenting code in that the diagrams generated are exactly what the code is doing. Here is a very simple example of plantuml sequence diagram:

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

If that is the output from your program, then:

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

This generates: myoutput.png (image). Where plantuml.jar is a free download from plantuml website... free and simple!

Upvotes: 0

Related Questions