[tor-commits] [tor/master] Re-think our doxygen warnings wrt missing docs and fatalness.

[nickm@xxxxxxxxxxxxxx]

commit d3e547b2bd93a5e43e90bda144971e243e092a57
Author: Nick Mathewson <nickm@xxxxxxxxxxxxxx>
Date:   Tue Nov 5 12:24:02 2019 -0500

    Re-think our doxygen warnings wrt missing docs and fatalness.
    
    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.
---
 Doxyfile.in         |  4 ++--
 changes/ticket32385 |  5 +++++
 configure.ac        | 18 ++++++++++++++++++
 3 files changed, 25 insertions(+), 2 deletions(-)

diff --git a/Doxyfile.in b/Doxyfile.in
index be500bbfa..0f8b111d9 100644
--- a/Doxyfile.in
+++ b/Doxyfile.in
@@ -767,7 +767,7 @@ WARNINGS               = YES
 # will automatically be disabled.
 # 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
 # potential errors in the documentation, such as not documenting some parameters
@@ -790,7 +790,7 @@ WARN_NO_PARAMDOC       = NO
 # a warning is encountered.
 # 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
 # can produce. The string should contain the $file, $line, and $text tags, which
diff --git a/changes/ticket32385 b/changes/ticket32385
new file mode 100644
index 000000000..2a4fc64f3
--- /dev/null
+++ b/changes/ticket32385
@@ -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.
diff --git a/configure.ac b/configure.ac
index 487361773..f3c955ad0 100644
--- a/configure.ac
+++ b/configure.ac
@@ -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.]))
+
+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
     AC_MSG_ERROR([Can't disable assertions outside of coverage build])
 fi



_______________________________________________
tor-commits mailing list
tor-commits@xxxxxxxxxxxxxxxxxxxx
https://lists.torproject.org/cgi-bin/mailman/listinfo/tor-commits