GNOME Bugzilla – Bug 684978
[html] [PATCH] EXTRACT_ALL leads to lots of unnecessary detailed sections
Last modified: 2014-01-05 11:02:52 UTC
Created attachment 225269 [details] [review] Patch to fix creation of unnecessary detailed sections Given a file with: /// X doc. class X { public: /// void mem(); void mem2(); }; and a default doxygen config, with EXTRACT_ALL = YES. The HTML class documentation of X will contain two empty detail sections, and links to both members will point to those detail sections. This is not necessary because the brief descriptions can act as links as well. The attached patch against r831 removes a check of in Memberdef::isDetailedSectionLinkable that always returned true with EXTRACT_ALL, but actually should not depend on it at all.
How can one reproduce the bug? On my machine I have 1.8.3.1 (the Fedora package doxygen-1.8.3.1-2.fc19.x86_64), and I did: renoir ~/tmp/test/doxygen $ ls test.hpp renoir ~/tmp/test/doxygen $ cat test.hpp /// X doc. class X { public: /// void mem(); void mem2(); }; renoir ~/tmp/test/doxygen $ doxygen -g Configuration file `Doxyfile' created. Now edit the configuration file and enter doxygen Doxyfile to generate the documentation for your project renoir ~/tmp/test/doxygen $ doxygen Doxyfile [...] And the generated file html/classX.html does not contain detailed description for mem() and mem2(), but only for X.
The EXTRACT_ALL option is defined as: "If the EXTRACT_ALL tag is set to YES doxygen will assume all entities in documentation are documented, even if no documentation was available." It doesn't say it will only assume all entities have a brief description, so I consider the current implementation to be correct. One can also argue that the detailed section does add more information in the sense that it shows a member definition out-of-line.