Flowcharting Method Calls

Absolutely.

Whenever I'm implementing something that I haven't done before (and the algorithm takes more than a few steps), I'll chart it out. I find that it really forces me to analyze the entire solution at a more atomic level and more thoroughly than if it wasn't charted out. I find that there are three major benefits to this practice:

• Fewer "oh craps" because I've thought the entire algorithm through
• Flushes out any potential knock on issues that may occur throughout the rest of the system
• Allows me to easily walk someone else through the algorithm

The two different occasions where I actually use these are:

• Low(ish) level algorithms. I mean a very specific solution to a very specific problem. I'll generally pass these by peers prior to implementation.
• User flow. Not only can I use this to pass by a peer, but I'll also use it to explain (in a very non-technical manner) flow to a usability expert.

Having said all that, I don't produce flowcharts daily (and even when they're done, it's a generally a whiteboard session unless I'm writing a technical design doc).

You probably will want either a full traditional state diagram or a summary pseudo-state diagram.

The full diagram would have a state circle for each of the (in your example) 72 states, and each of the transitions (including self loops). Such a diagram is good for documentation and study for modifications. It is easier to deal with than the C code as it suppresses the irrelevant verbiage.

A summary diagram would be better for an introduction to the state machine code. It would require you to figure out some "super states" that represent groups of real states. This is often not too hard. In your example, it looks like the states with the "NS_HTML5TOKENIZER_COMMENT" name prefix can be grouped together, for instance. So in your diagram you would have one "comment parsing" super state to represent these 6 six real states. Then you make a fairly normal state diagram using these super states, showing the major transitions (or all, if you want accuracy) between the super states. This reduces the complexity of the diagram and show the major functions going on in the machine.