From Nsnam
Revision as of 21:28, 26 November 2013 by Tommaso (Talk | contribs)

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 he 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
4086 lte
1903 wifi
1727 wimax
1416 core
696 network
466 mesh
368 uan
363 dsr
259 mobility
237 spectrum
209 propagation
191 olsr
188 applications
171 stats
133 netanim
133 config-store
129 visualizer
126 buildings
84 energy
48 openflow
47 point-to-point
46 dsdv
41 point-to-point-layout
39 mpi
38 aodv
33 fd-net-device
30 bridge
24 brite
22 nix-vector-routing
21 antenna
18 emu
17 virtual-net-device
16 csma
11 tap-bridge
8 csma-layout

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 script will make a long list of warnings. You're probably interested in the ones from a single module. The following command might help:

 grep <module name> doc/doxygen.warnings.log | sort > doc/my.doxygen.warnings.txt

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.