Bugzilla – Bug 1521
doxygen warnings are being underreported
Last modified: 2012-11-09 21:03:08 UTC
./waf --doxygen will leave a doc/doxygen.warnings.log One can generate a report using "bash doxygen.warnings.report.sh" script: Summary Report of Doxygen warnings: Count of warning by module: Count Module 75 /src/lte 67 /src/dsr 41 /doc/introspected-doxygen.h 40 /src/olsr 28 /src/core 13 /src/internet 8 /src/openflow 2 /src/network 2 /src/netanim 1 /src/propagation + 120 undocumented parameters. grep: doxygen-r7657.conf: No such file or directory R7657 sorted tags in: doxygen-r7657.conf.tags Sorted doxygen tags in: doxygen.conf.tags Changed doxygen tags in: doxygen.conf.tags.changed, (290 lines) ------ The current log is underreporting warnings. We have a lot of undocumented parameters. For example, WimaxChannel::GetDevice(uint32_t i) has an undocumented parameter (and there are many such in wimax) but there is no warning listed above for src/wimax, nor is this in the log itself (i.e. it is not a problem of the bash script). In addition, with regard to this bash script, I'm not sure about the last four lines of output in the above; what is r7657, and what is intended with doxygen.conf.tags and doxygen.conf.tags.changed?
I'll have to refresh my memory about the end of the report. Please stand by...
The last four lines are obsolete. (I added them to generate a summary file of the changes to the doxygen config file.) For some reason I had set "EXTRACT_ALL = yes", which tells doxygen to pretend that all items are documented, even when they aren't. With that set back to the default, I get the report below. (Note wimax is now ranked fifth.) I checked the report script, and the number is a lower bound (multiple undocumented params in function are counted as a single warning). I'll update the config and report script. Summary Report of Doxygen warnings: Count of warning by module: Count Module 4750 /src/core 2337 /src/wifi 2021 /src/internet 1973 /src/lte 1771 /src/wimax 1170 /src/network 572 /src/dsr 516 /src/mesh 477 /src/visualizer 458 /src/uan 285 /src/propagation 276 /src/mobility 269 /src/spectrum 216 /src/stats 205 /src/olsr 201 /src/test 201 /src/applications 186 /src/buildings 182 /utils/grid.py 149 /src/netanim 142 /src/flow-monitor 138 /src/config-store 113 /src/tools 109 /src/energy 78 /src/antenna 76 /src/dsdv 65 /src/aodv 53 /src/point-to-point 50 /src/openflow 43 /doc/introspected-doxygen.h 42 /src/topology-read 41 /src/point-to-point-layout 40 /utils/print-introspected-doxygen.cc 38 /utils/check-style.py 37 /src/mpi 36 /src/virtual-net-device 34 /src/nix-vector-routing 32 /src/bridge 19 /src/emu 19 /src/csma 17 /utils/python-unit-tests.py 11 /src/tap-bridge 9 /utils/bench-simulator.cc 8 /utils/bench-packets.cc 8 /src/csma-layout + 119 additional undocumented parameters. (All counts are lower bounds.)
Changeset 9dc069207a90 http://code.nsnam.org/ns-3-dev/rev/9dc069207a90
I've rediscovered why I set "EXTRACT_ALL = yes". Without it, undocumented functions appear only in the list of functions for the class. They have no individual section showing what they call, who calls them, or implementation source. I don't have any good ideas on how to resolve this, except by brute force: * Keep "EXTRACT_ALL = yes" normally * Switch to "EXTRACT_ALL = no" when we want to run the report and see what still needs work.
To generate all doxygen docs I reverted the doxygen.conf file to use: "EXTRACT_ALL = yes" Changeset: 257f931d13e1 http://code.nsnam.org/ns-3-dev/rev/257f931d13e1 For doxygen.warnings.report.sh, I edited the script to modify the doxygen.conf file to use: EXTRACT_ALL = no HAVE_DOT = no # for speed then run the report generator. There's a significant time penalty (running doxygen separately for the report) but we get a better picture of what needs work. Changeset: a2c0863500a9 http://code.nsnam.org/ns-3-dev/rev/a2c0863500a9 Future work: run the script from cron and post the results automatically, perhaps to the wiki?
I augmented the reporting script to: - generate a second list of all files with errors - summarize by * total number of directories (currently 119) * total number of files (1270) * total number of warnings (19488) Commit: 9e2f5cd09b7e http://code.nsnam.org/ns-3-dev/rev/9e2f5cd09b7e I fixed the ~950 warnings in doc/introspected-doxygen.h Commit: e4e4a089b802 http://code.nsnam.org/ns-3-dev/rev/e4e4a089b802