nihilist/tor
1
0
Fork 0
mirror of https://gitlab.torproject.org/tpo/core/tor.git synced 2024-11-27 13:53:31 +01:00
Code Issues Packages Projects Releases Wiki Activity

Re-think our doxygen warnings wrt missing docs and fatalness.

Browse Source 
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.
This commit is contained in:
Nick Mathewson 2019-11-05 12:24:02 -05:00
parent 884056ae57
commit d3e547b2bd
3 changed files with 25 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
Doxyfile.in
View File

@ -767,7 +767,7 @@ WARNINGS = YES
# will automatically be disabled. # will automatically be disabled.
# The default value is: YES. # The default value is: YES.
WARN_IF_UNDOCUMENTED = YES WARN_IF_UNDOCUMENTED = @DOXYGEN_WARN_ON_MISSING@
# If the WARN_IF_DOC_ERROR tag is set to YES, doxygen will generate warnings for # If the WARN_IF_DOC_ERROR tag is set to YES, doxygen will generate warnings for
# potential errors in the documentation, such as not documenting some parameters # potential errors in the documentation, such as not documenting some parameters
@ -790,7 +790,7 @@ WARN_NO_PARAMDOC = NO
# a warning is encountered. # a warning is encountered.
# The default value is: NO. # The default value is: NO.
WARN_AS_ERROR = NO WARN_AS_ERROR = @DOXYGEN_FATAL_WARNINGS@
# The WARN_FORMAT tag determines the format of the warning messages that doxygen # The WARN_FORMAT tag determines the format of the warning messages that doxygen
# can produce. The string should contain the $file, $line, and $text tags, which # can produce. The string should contain the $file, $line, and $text tags, which

5
changes/ticket32385 Normal file
View File

@ -0,0 +1,5 @@
o Minor features (doxygen):
- 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.

18
configure.ac
View File

@ -76,6 +76,24 @@ AC_ARG_ENABLE(nss,
AC_ARG_ENABLE(pic, AC_ARG_ENABLE(pic,
AS_HELP_STRING(--enable-pic, [Build Tor's binaries as position-independent code, suitable to link as a library.])) 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.]))
if test "$enable_missing_doc_warnings" = "yes"; then
DOXYGEN_FATAL_WARNINGS=NO
DOXYGEN_WARN_ON_MISSING=YES
elif test "$enable_fatal_warnings" = "yes"; then
# Fatal warnings from doxygen are nice, but not if we're warning about
# missing documentation.
DOXYGEN_FATAL_WARNINGS=YES
DOXYGEN_WARN_ON_MISSING=NO
else
DOXYGEN_FATAL_WARNINGS=NO
DOXYGEN_WARN_ON_MISSING=NO
fi
AC_SUBST(DOXYGEN_FATAL_WARNINGS)
AC_SUBST(DOXYGEN_WARN_ON_MISSING)
if test "x$enable_coverage" != "xyes" -a "x$enable_asserts_in_tests" = "xno" ; then if test "x$enable_coverage" != "xyes" -a "x$enable_asserts_in_tests" = "xno" ; then
AC_MSG_ERROR([Can't disable assertions outside of coverage build]) AC_MSG_ERROR([Can't disable assertions outside of coverage build])
fi fi