Reduce doxygen warnings #3115
Reduce doxygen warnings #3115
Conversation
Doxygen was giving a warning message about "multiple use of section label 'deprecated'", so this commit changes the section label. There are no references to this section, so the label is only changed in one place. (I can't find any other uses of this section label, so the warning message seems to be wrong, but it doesn't hurt to fix it.)
Delete documentation for parameters which no longer exist
johnnonweiler
requested review from
cesaro,
chrisr-diffblue,
cristina-david,
kroening,
martin-cs,
NathanJPhillips,
peterschrammel,
pkesseli,
romainbrenguier,
smowton,
tautschnig and
thk123
as code owners
There was a problem hiding this comment.
The changes look basically sound, so I'm happy with those - but I note that CI is failing for the doxygen run, so that will need to be fixed before this is merged. I'm not immediately seeing why it is failing, so it may just be a travis glitch that is resolved with a build restart - but needs investigating.
| @@ -90,7 +90,7 @@ is initially populated from `irep_ids.def`, so for example the fourth entry | |||
| in `irep_ids.def` is `“IREP_ID_ONE(type)”`, so the string “type” has index 3. | |||
| You can refer to this \ref irep_idt as `ID_type`. The other kind of line you | |||
| see is `“IREP_ID_TWO(C_source_location, #source_location)”`, which means the | |||
| \ref irep_idt for the string “#source_location” can be referred to as | |||
| \ref irep_idt for the string “\#source_location” can be referred to as | |||
There was a problem hiding this comment.
Maybe this change doesn't actually achieve what it is supposed to do? Doxygen now appears to be complaining that the link request could not be satisfied.
There was a problem hiding this comment.
This changed worked. The problem is the other #source_location on the previous line. (I'm not sure how I missed this earlier!)
This has turned out to be much more tricky to fix - adding a \ doesn't work in this case (as explained in https://stackoverflow.com/a/36750674 ). I haven't found a perfect solution to this, but have now committed something that works with slightly different double quotes.
There was a problem hiding this comment.
I think this is good, especially with the elaborate commit message. It's not beautiful, but anyone can easily figure out what's going on here.
Doxygen produced a warning about a reference it couldn't find, because of a '#' symbol used in the comment (which the author didn't intend to be a reference). Usually, '#' could be escaped '\#', but that doesn't work in this case, because it appears within quotes (as explained in https://stackoverflow.com/a/36750674 ). I couldn't find a way to get this to work with the quotes that had been used, so I have changed it to use different quotes.
|
@tautschnig, @chrisr-diffblue please could you let me know if you're still happy with this, given my additional commit? |
|
It's a bit ugly, but it does look like this is the only workaround to what seems like a weakness in Doxygen. As such, I'm OK with the additional tweak. I'm agnostic on whether this additional commit should be squashed into the earlier commit or not. |
|
I'd prefer not to squash it, as it is actually completely independent from the change in the previous commit. (Travis is supposed to only complain about doxygen issues on lines which have been changed, but in this case doxygen was reporting the wrong line number in its warning message.) |
There was a problem hiding this comment.
This PR failed Diffblue compatibility checks (cbmc commit: eea5403).
Build URL: https://travis-ci.com/diffblue/test-gen/builds/87214638
Status will be re-evaluated on next push.
Please contact @peterschrammel, @thk123, or @allredj for support.
Common spurious failures:
- the cbmc commit has disappeared in the mean time (e.g. in a force-push)
- the author is not in the list of contributors (e.g. first-time contributors).
There was a problem hiding this comment.
Passed Diffblue compatibility checks (cbmc commit: eea5403).
Build URL: https://travis-ci.com/diffblue/test-gen/builds/87214638
Following on from #3082, this addresses some more low hanging fruit for reducing the number of warnings when running doxygen. Please see the individual commits for details.