Re-think our doxygen warnings wrt missing docs and fatalness. #1502
Conversation
Up till now, we have warned about all missing documentation, which meant that we could never make doxygen warnings fatal. This has led to our doxygen output getting full of errors several times in the past. This commit changes our approach to doxygen warnings: missing documentation warnings are only on when the user asks for them with --enable-missing-doc-warnings. When that option is not present, doxygen respects the --enable-fatal-warnings flag. Closes ticket 32385.
Pull Request Test Coverage Report for Build 7120
|
tlyu
reviewed
Nov 6, 2019
configure.ac
Outdated
| @@ -76,6 +76,24 @@ AC_ARG_ENABLE(nss, | |||
| AC_ARG_ENABLE(pic, | |||
| AS_HELP_STRING(--enable-pic, [Build Tor's binaries as position-independent code, suitable to link as a library.])) | |||
|
|
|||
| AC_ARG_ENABLE(missing-doc-warnings, | |||
| AS_HELP_STRING(--enable-missing-doc-warnings, [Tell doxygen to warn about missing documentation.])) | |||
This seems like it would make all Doxygen warnings (not just missing documentation) non-fatal, which seems like a reasonable constraint. Maybe we want to highlight this side effect in the help text and changes file?
tlyu
reviewed
Nov 7, 2019
| @@ -2,4 +2,5 @@ | |||
| - Our "make doxygen" target now respects --enable-fatal-warnings by | |||
| default, and does not warn about items that are missing documentation. | |||
| To warn about missing documentation, run configure with the | |||
| "--enable-missing-doc-warnings" flag. Closes ticket 32385. | |||
| "--enable-missing-doc-warnings" flag: doing suspends fatal warnings | |||
s/doing/doing so/ ?
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Up till now, we have warned about all missing documentation, which
meant that we could never make doxygen warnings fatal. This has led
to our doxygen output getting full of errors several times in the
past.
This commit changes our approach to doxygen warnings: missing
documentation warnings are only on when the user asks for them with
--enable-missing-doc-warnings. When that option is not present,
doxygen respects the --enable-fatal-warnings flag.
Closes ticket 32385.
The text was updated successfully, but these errors were encountered: