Doxygen-warnings

From Nsnam
Jump to: navigation, search

Main Page - Current Development - Developer FAQ - Tools - Related Projects - Project Ideas - Summer Projects

Installation - Troubleshooting - User FAQ - HOWTOs - Samples - Models - Education - Contributed Code - Papers

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
3209 lte
1537 wimax
1138 wifi
521 mesh
459 visualizer
236 dsr
227 netanim
211 wave
210 spectrum
195 olsr
150 core
127 aodv
108 config-store
98 buildings
90 mpi
87 energy
74 dsdv
46 openflow
28 brite
22 nix-vector-routing
20 network
18 antenna
17 virtual-net-device
15 internet
2 propagation
2 sixlowpan
2 topology

How to proceed

The procedure is simple.

  1. Post online that you're working on a module. Eventually coordinate with who's already working on the same module.
  2. Follow the direction in the Sprint page to setup Doxygen to show you the warnings.
  3. Start with base classes. Mind that virtual functions can (and should) be documented only in the base class.
  4. Don't be afraid of the numbers. I was able to kill 1400 warnings in 2 days (just in my spare time).
  5. Once you have a patch, post it in Bugzilla: Bug 938: missing Doxygen in ns-3.
  6. 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.

User's opinions

Some time ago I did a poll, an I asked the users the documentation they need most. Here is the result.

UsersPollResults.png

--Tommaso (talk) 16:29, 26 November 2013 (EST)