Doxygen warning removal
This page is to help coordinating the efforts in fixing Bug 938: missing Doxygen in ns-3.
As a followup of Friday November 15 ns-3 Sprint, we'd like to coordinate the efforts of Doxygen warning removal.
It must be pointed out that warning removing is not good per-se. It is a way to complete the documentation and make it better.
Undocumented functions leads to poor coding and, ultimately, not be able to use the ns-3 full power.
Moreover, bad or missing documentation means bugs !
Doxygen work status
The following table might seems overwhelming. And the warning are just the ones in the model and helper folders.
However, mind that many are chain-warnings, meaning that once you fix the master one in the base class, many of them will disappear. More on that at the bottom of the page.
The current doxygen warning status, by module is:
|Number of warnings||Module||Who's working on it|
How to proceed
The procedure is simple.
- Post online that you're working on a module. Eventually coordinate with who's already working on the same module.
- Follow the direction in the Sprint page to setup Doxygen to show you the warnings.
- Start with base classes. Mind that virtual functions can (and should) be documented only in the base class.
- Don't be afraid of the numbers. I was able to kill 1400 warnings in 2 days (just in my spare time).
- Once you have a patch, post it in Bugzilla: Bug 938: missing Doxygen in ns-3.
- Go drink a beer, you deserve it.
Hint and tips
The doxygen.warnings.report.sh script will make a long list of warnings. You're probably interested in the ones from a single module. The script has a number of options which can help:
$ doc/doxygen.warnings.report.sh -h ... Usage: doxygen.warnings.report.sh [-eithv] [-s <log-file> | -l | -w] [-m <module>] [-f <regex>] [-F <regex>] ... -e Filter out warnings from */examples/* -t Filter out warnings from */test/* -m Only include files matching src/<module> -f Only include files matching the <regex> -F Exclude files matching the <regex>
Note the -m <module>, -e and -t options. The -m <module> will show the full warning messages from just files in src/<module>.
Now you have a shorter list of bugs to work with. Cut out the ones from the tests and examples (or not, depends on how pedantic you are). Those are your warnings to kill.
Some time ago I did a poll, an I asked the users the documentation they need most. Here is the result.