views:

37

answers:

1

I have some large, mostly procedural codes that need to be well documented. This generally involves repeated use of a number of functions that must be executed in a certain order.

Doxygen is a great product, but it seems very oriented towards documenting OOP codes. Does anyone have any tips on how to use doxygen in a natural way to document procedural work?

+1  A: 

There's nothing inherently OOP about the way doxygen works. It's just able to extract more information about OO code because it has more information in it (e.g., inheritance graphs).

We use doxygen for plain C code and it works just as well, minus the information that plain C doesn't provide when compared to C++. Just use doxygen's grouping (@addtogroup et al) features to organize the generated documentation and you're good to do.

vanza
So what about enumeration type things, not just documenting individual functions or grouping them, but actually showing them in some kind of order?For example, the main iterative part of the program has to call, say, 20-40 functions in a specific order. I'd like to be able to stick some kind of comment block above each function call in that one large routine that describes what's being done, and have the output of the large routine be some kind of ordered list.
Aurelius
If you have a bunch of functions that need to be called in a certain order, then you should document *that* in those functions APIs - probably grouping them together in a group, and have the group description say how they're supposed to be used together. But you don't document that fact at the call sites.
vanza
Thanks, I'll give this a try today and see how it works out.I had preferred to document these things at the call sites, as this is a CUDA program, and the way in which the kernels are called with additional grid/thread/memory arguments changes the behavior of the kernels themselves. i.e., information/arguments are present at the call sites that aren't visible in the functions themselves.
Aurelius