Doxygen help to document error messages
Brought to you by:
dimitri
Menu
▾
▴
Doxygen is impressive. It generates nice documentation (especially for a web site output) – even for a doxygen newbie at it like me (I’ve been playing with it for a few days trying to get familiar with its many features). Yet there is one problem I have not been able to see a solution for without thinking of needed additional functionality.
I work with a project that has lots of source files (C language), with lots of functions, lots of lines – and lots of error messages that some would like to see documented. A goal would be an alphabetical list of error messages that one can scroll down looking for the one that is current causing concern, click on it the message, which takes/shows them (1) a detailed description of the problem and (2) a recommendation for what can be done to resolve the problem [likely someone not familiar with the code]. And for the technical person that may eventually get the call about the error, information as to which function and source file line the error occurred in.
I generated a (Word) document once that had this information. But as you can guess, this can quickly become out dated an inaccurate (and it’s a boring non-hyperlinked file). And it is a lot of work. If I could use Doxygen, then programmers could have this information in the source (and hopefully update it as error messages change or get added) and then have the references updated on a new doxygen rebuild of the documentation.
The doxygen manual showed a trick that I tried to adapt. After an error message is generated in the code, it is followed by doxygen commands to document the error with the message, a description, and a recommendation such as (just an example):
fprintf(errorreportdevice, “The configuration file (%s) is missing.\n”, parameters->cfgfile);
/// \error
/// <B>The configuration file (FILE) is missing.</B>\n
/// The configuration file is specified on the command line with the –c switch when the program is invoked.
/// The file name is specified after the –c switch with white space in between. If it is not specified, the file
/// name defaults to \“cfg.txt\”.\n
/// <I>Recommend: check that the file specified on the command line exists in the directory where the
/// the program was invoked. If the –c switch was not given, the file cfg.txt should be there. </I>
[And I added to my ALIASES definition: error=\xrefitem error_msgs “Error Message” “List of Errors”.]
When I try the above, the resulting web site (I generate html output) gives me a nice “Related Pages” tab with a “List of Errors” link on that page. That link takes me to a page titled “List of Errors” with boxes for each function and in each box a paragraph for each documented error (that gives the same information as put in the source (as in the above example). I can click on the function name, on the box, to go to the function documentation. If I do that, I go to the nice function documentation with the error message text in a paragraph under a heading “Error Message:” (one for each error message paragraph).
The main problems that I see, which I cannot resolve, are:
* No alphabetized index of error messages that can be quickly navigated. The error messages are given, with full details, grouped by function – not as easy to browse by one that only has an error message to go with.
* No way to provide a link to the line in source code so that a technical person could research the problem more (if needed). However, it is nice to have the error message documentation in the function documentation. Though a large function, with lots of messages, would begin to look cluttered (this should not happen in good design but does happen in legacy code).
I next tried to add a \anchor some_unique_tag to after the \error, but that didn’t help much. Plus to require programmers to come up with unique anchor tags at each error message seems excessive and prone to errors.
After some thinking, I thought I could write a script/program that is run before doxygen that generates a file of doxygen commands to create a page of alphabetical error messages (as well as creating a file and line number cross-reference to use later). Outside of a few preamble lines (like \page…) it would mostly be a list of lines (in a comment block) like:
\ref some_unique_tag “The configuration file (FILE) is missing.”\n
But then, how to take care of the some_unique_tag? I didn’t want the programmer to burden with this. And I don’t want a script to alter the source code (don’t want to confuse revision control systems, etc.). So at a dead-end.
To do something with the source code line references, I thought of perhaps writing a post-doxygen script that fixes up the html from the cross-reference created from the pre-doxygen script. But that also relied the anchors being unique (some_unique_tag again) so that the script could search for that part of the html files and do some editing. Dead-end again.
It would be great if doxygen had some environment/context variable ability that could present unique information – such as CURRENT_FILE_NAME, CURRENT_LINE_NUMBER, REF_COUNTER, etc. with some kind of way to use it to have unique anchors automatically generated. Though that alone probably would not help due the requirement to not change the source code directly.
Perhaps doxygen could have “hooks” that can be configured to run user scripts/programs at key places in the generation states. Not only pre-doxygen and post-doxygen script hooks, but perhaps a hook for a \hook command that runs when encountered in generation. The script could be presented with context information (such as current file name, line number, text around the command, etc.). Then perhaps the hook script output could be presented as if it was doxygen text from the source file (to be used by doxygen further). [Seems like this is a lot like CGI programming in web pages.]
Perhaps I should just give in and write a program that generates a stand-alone html file that has all that is needed. Then just reference this file in doxygen commands within the source. That seems like a lot of work and wouldn’t be as integrated into the doxygen output.
I just brainstormed a little assuming that the problems above did not have a solution in current doxygen design. Plus I do not know the internal design of doxygen. If my suggestions have merit, there should really be more to their design done to optimize any extenstion to doxygen. If there are easier (and doable) ways to accomplish what my original goal was, I am more than willing to try them.
I’m sorry for the length of this message and appreciated it you read it all.
Maybe give \defgroup and \ingroup a try. Define a group for errors and you can add anything related using the \ingroup tag.