Doxygen-warnings

Main Page - Roadmap - Summer Projects - Project Ideas - Developer FAQ - Tools - Related Projects

HOWTOs - Installation - Troubleshooting - User FAQ - 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.

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