|
Bugzilla – Full Text Bug Listing |
| Summary: | doxygen warnings are being underreported | ||
|---|---|---|---|
| Product: | ns-3 | Reporter: | Tom Henderson <tomh> |
| Component: | documentation | Assignee: | Mitch Watrous <watrous> |
| Status: | RESOLVED FIXED | ||
| Severity: | normal | CC: | ns-bugs, pdbarnes |
| Priority: | P5 | ||
| Version: | pre-release | ||
| Hardware: | All | ||
| OS: | All | ||
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 |
./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?