Graphviz for documentation

Question

I noticed that doxygen uses the graphviz library for creating diagrams. Have you ever used graphviz for generating documentation? Is it worth learning the graphviz for documentation purposes outside the scope of doxygen? Or am I better off to sticking with a standard data modeling package like Visio?

I understand the merits of it as a graphing library, but for trying to represent more complex UML (or similar) is it still worth looking into?

Answer 1

The graphviz is very very simple language/format for creating graphs. If the capabilities are enough for you I would recommend it (Its so easy, that I would estimate the time to learn with at most 1 hour).

Answer 2

If you're just talking about creating inheritance/collaboration diagrams like Doxygen does, it's worth investigating IDEs that will do that for you automatically. For from-scratch or hand-tuned documentation, I use OmniGraffle (since I'm on a Mac) which I highly recommend.

However, GraphViz and DOT can be really handy, not only for documentation, but for debugging and code comprehension as well, particularly for data structures. I generally don't write DOT by hand, but automatically-generated DOT can be well worth the minimal effort.

One of the places I've found GraphViz extremely useful is for understanding and debugging binary search tree algorithms. I develop CHDataStructures.framework, an open-source Objective-C framework, which includes several varieties of BSTs. I implemented two methods: -(NSString*)dotGraphString on the parent class and -(NSString*)dotGraphStringForNode: on each child class. In about 30-40 lines of code (most of it at the bottom of CHAbstractBinarySearchTree.m), I added the ability to iteratively traverse a binary tree and create a DOT representation of it, including balancing information, coloring nodes red or black, etc. (With a little care, you can easily represent null sentinel nodes and display the tree in proper sorted order.)

In my test code, after each modification of the tree, I called -dotGraphString and saved the result to a .dot file, stopped there with a breakpoint, then opened that file with GraphViz, which is smart enough to re-render the DOT graph when the file is updated. This approach made it vastly easier to see what was happening in the tree and spot bugs in my implementation of a given algorithm. This approach can be adapted fairly easily for various kinds of data structures, and is generally much faster and easier than creating a UI just for visualizing the structure.