Easy to use UML-like documentation methods

Question

Hi,

I am working on product which is essentially procedural (C) code in OOPs body (C++) resulting in hard to understand architecture. As I dig through the code, I want to document my understanding in simplified notation. To give an example I would like to document a given function in following format

Function

• Library
• Module
• Component
• Description
• Function Attribute

Function Attribute

• Message Handler

  *Message_Name : Message*

• Creator Function

• Access Function

I would like the method to a. be simple to use and b. allow me to the format easily

I have earlier read UML, but generally find it inconvenient to use for my purpose. Is it possible to accomplish this?

Regards,

PS. I have thought of documenting functions as stereotypes in UML. Is it crazy?

Answer 1

I'm not convinced that separate document in UML form or otherwise is the best approach here. The problem is that you create something that even if it's right now will become obsolete over time.

I would more inclined to use a Javadoc-style approach. Add structured comments into the code. Many of the things you are documenting would really help the code maintainer in the code, so why not put them there? Then if you want separate documention too, run an extracter. From this you can build navigable web-pages (as does Javadoc).

You don't say what language you are using, but I was using this style of documentation in C waaay back before Java came along. A quick Google yields Doxygen as an example of a technique.

Once you've got the major components documented at this level you might then choose to use UML to show key relationships between components and classes.