The software group I currently work in has recently decided to start documenting our codebase. The initial approach they have been taking was to use the built in triple slash /// method of documenting.
A newer issue we began to find was that the result of running this through doxygen is a very nice representation of the codebase but for a programmer to use, where we had intended for this documentation to be readable by our Systems Engineers who will often come to us asking what a task is doing exactly.
Is there an easy way to document our code using the /// method and doxygen in a manner that if we run it a certain way, we can generate a document that JUST contains the Systems engineering version of documentation without all the extra fluff of a standard programmers documentation that would scare away a systems guy such as methods and member variables etc.? Any alternative solution suggestions are also welcome.
I’m sorry if this is a little confusing as to what we are trying to accomplish, I can adjust as responses come in.
Thank you.
One thing you can do is to use doxygen’s
\pagecommand, which gives you “Related Pages”. Create a textfile with an extension that is processed by doxygen, and just put a comment in there. (I use .doc, but you might want to change that to something else to avoid confusion with Word documents. I am also putting these files in a common directory calleddocsrcto have them at one place.) These pages then show up in a seperate section in the docs.You can then create links to the page or the sections with
\ref foobaror\ref step1.In our project, basically everyone who uses the program also codes around with it, so it is nice to have the usage documentation cross-linked with the code. But as the others pointed out, it might not be the best solution for a typical enduser-documentation.