doxygen
Feature request: add a WARN_IF_GROUPING_ERROR
I found that this is a common error when writing code, and it's only shown when WARNINGS = YES, which makes it hard to spot selectively.
Even though the goal should be to have no warnings at all, sometimes you have them, and sometimes you have a LOT of them (like, in ns-3 we consider ourself pedantic, and we have 4977 warnings, ouch).
It would be useful to have the possibility to selectively enable warnings about bad groups, which can happen for a number of reasons:
- Misspelling,
- Removal of a group (and forgetting to update all the files)
- Forgot to add \defgroup,
- And the list can go on, and on.
In particular, the warnings that I'd like to be activated when WARN_IF_GROUPING_ERROR = YES should be:
-
warning: missing title after \defgroup -
warning: Found non-existing group -
warning: Member <x> found in multiple @ingroup groups
but these are the ones showing up in our log, there might be more relevant to groups.
Some thoughts.
That are a lot of warnings and it is often hard to start fixing them (one doesn't see where to start). In principle, like you wrote as well, one should have no warnings at all.
Regarding the "group" warnings, I don't think it is wise to have here a special category as this might influence the behavior of the output. It is also easy to filter them out, with tools like grep, sed, sort and uniq one can filter quite well (this also is valid for other warnings).
When looking at the warning we also see warnings about not generated graphs like:
Caller graph for 'ns3::Time::GetSeconds' not generated, too many nodes (223), threshold is 70. Consider increasing DOT_GRAPH_MAX_NODES.
It makes sense to have the number of nodes in a graph limited as otherwise they get (especially with fixed formatted output) unreadable.
When having HTML output it is worth to set DOT_IMAGE_FORMAT to svg and also to set INTERACTIVE_SVG=YES.
Furthermore when one has really big graphs (like for ns3::Simulator::Now) one should have a look at the commands like \hidecallgraph / \hidecallergraph to selectively disable these graphs.
@albert-github Since we will probably forever get requests to enable or disable certain warnings, maybe we should generalize things and give each warning a unique identifier and category.
Then the user can enable all warnings, but disable a certain category or even one or more individual warning messages. Or alternatively, a user can disable all warnings, except for a category or set of warnings they care about. For example:
WARNINGS = YES
WARNINGS_DISABLE = doc W10020
WARNINGS_ENABLE =
or
WARNINGS = NO
WARNINGS_DISABLE =
WARNINGS_ENABLE = group W30000 W20012
In the code
warn(file,line,WarnCategory::Doc,WarnID::W20,"Some warning about the documentation")
We would probably need a script to extract the warn statements and generate a documentation page listing all warnings with their text and check for the uniqueness of the IDs in the code.
Just a thought.
@doxygen
I fully agree.
It will be quite a bit of work to extract all the warnings and categorize / group them properly (this is something that withheld me / us from implementing it). A quick search gave me over 500 warnings, over 200 err calls and 38 term callsI think it is not only concerns the thewarncalls but also theerrandtermcalls and there might be some interaction with theWARN_AS_ERROR` setting.
Should we make the warning numbers decimal numbers or hexa-decimal?
@albert-github I was thinking about decimal numbers, and encode the category as well, e.g. category*10000+id, so that W10010 is for instance a documentation error and W20001 a grouping error (just an example). This also making filtering easy.
@doxygen that was the same reasoning why I also thought about hexa-decimal numbers so operators (| and & could work on it) but in principle it won't make much difference only that for users decimal numbers might be better understandable.
The big question will be who will do what?
Warning codes would do perfectly, I support the idea.
About why I asked for the feature, there is a reason. Some warnings are of particular interest for the contributors, and our Ci is instrumented to prevent a MR to go on if there are some classes of doxygen warnings, mainly undocumented functions / classes.
However, we have some "unavoidable" warnings, like classes that we don't want to document fully for specific reasons, but that are going in the documentation anyway. An example is cairo_*, which is code borrowed, and that we don't want to modify (but we want in the documentation). Probably we can find a way to avoid the warnings, but it's just an example.
Plus, there are some warnings that are not really relevant to the contributors, and that must be fixed by the maintainers, like the ones generated by macros.
Hence, it's useful to be able to break down the warnings into categories, so that we can filter them and show to the contributors only the ones that are relevant to them.
About the categories, if this is going to be implemented (I hope so), it would be great to have the warning log report the warning code, e.g.: warning (W30000): missing title after \defgroup.
Numbering... I'll leave it to your ultimate decision, but I'd suggest a positional Hex format, like: W1xxx - missing documentation for a class/function, W2xxx - grouping stuff, etc. In this way it's easier to grep the codes.
Btw, thanks for the suggestions on the image and DOT parts, we'll implement them.