fix -Wdocumentation -Werror=documentation logic in configure.ac #22185

flip the logic so you do not check for documentation consistency during compile time if suppression is disabled

I noticed even though on CI warnings are suppressed the documentation preprocessor flag was still being set:

https://github.com/bitcoin/bitcoin/blob/master/ci/test/06_script_a.sh#L17

NACK.

The reason it's currently done this way (only enable -Wdocumentation when passing --enable-suppress-external-warnings) is to prevent regular builders from seeing warnings. For example, if you build this branch on macOS, using libraries installed via brew, you'll see 1000s of warnings from libevent, boost etc (small except below). The current implementation is enough to prevent new -Wdocumentation issues from occurring in our code, as the CI uses --enable-suppress-external-warnings and -Werror.

./autogen.sh
./configure
gmake -j9
....
In file included from test/miner_tests.cpp:24:
In file included from /usr/local/include/boost/test/unit_test.hpp:18:
In file included from /usr/local/include/boost/test/test_tools.hpp:46:
In file included from /usr/local/include/boost/test/tools/old/impl.hpp:19:
In file included from /usr/local/include/boost/test/unit_test_log.hpp:18:
/usr/local/include/boost/test/tree/observer.hpp:45:20: warning: parameter 'number_of_test_cases' not found in the function declaration [-Wdocumentation]
    //! [@param](/bitcoin-bitcoin/contributor/param/)[in] number_of_test_cases indicates the number of test cases. Only active
                   ^~~~~~~~~~~~~~~~~~~~
/usr/local/include/boost/test/tree/observer.hpp:47:20: warning: parameter 'root_test_unit_id' not found in the function declaration [-Wdocumentation]
    //! [@param](/bitcoin-bitcoin/contributor/param/)[in] root_test_unit_id the ID root of the test tree currently being tested
                   ^~~~~~~~~~~~~~~~~
/usr/local/include/boost/test/tree/observer.hpp:66:20: warning: parameter 'test_unit' not found in the function declaration [-Wdocumentation]
    //! [@param](/bitcoin-bitcoin/contributor/param/)[in] test_unit the test being executed
                   ^~~~~~~~~
/usr/local/include/boost/test/tree/observer.hpp:71:16: warning: parameter 'elapsed' not found in the function declaration [-Wdocumentation]
    //! [@param](/bitcoin-bitcoin/contributor/param/) elapsed duration of the test unit in microseconds.
               ^~~~~~~
4 warnings generated.
....
In file included from bitcoin-cli.cpp:31:
/usr/local/include/event2/buffer.h:210:11: warning: parameter 'buffer' not found in the function declaration [-Wdocumentation]
 * [@param](/bitcoin-bitcoin/contributor/param/) buffer the evbuffer that the callback is watching.
          ^~~~~~
/usr/local/include/event2/buffer.h:210:11: note: did you mean 'buf'?
 * [@param](/bitcoin-bitcoin/contributor/param/) buffer the evbuffer that the callback is watching.
          ^~~~~~
          buf
/usr/local/include/event2/buffer.h:211:11: warning: parameter 'cb' not found in the function declaration [-Wdocumentation]
 * [@param](/bitcoin-bitcoin/contributor/param/) cb the callback whose status we want to change.
          ^~
/usr/local/include/event2/buffer.h:211:11: note: did you mean 'buf'?
 * [@param](/bitcoin-bitcoin/contributor/param/) cb the callback whose status we want to change.
          ^~
          buf
/usr/local/include/event2/buffer.h:219:11: warning: parameter 'buffer' not found in the function declaration [-Wdocumentation]
 * [@param](/bitcoin-bitcoin/contributor/param/) buffer the evbuffer that the callback is watching.
          ^~~~~~
/usr/local/include/event2/buffer.h:219:11: note: did you mean 'buf'?
 * [@param](/bitcoin-bitcoin/contributor/param/) buffer the evbuffer that the callback is watching.
          ^~~~~~
          buf
/usr/local/include/event2/buffer.h:220:11: warning: parameter 'cb' not found in the function declaration [-Wdocumentation]
 * [@param](/bitcoin-bitcoin/contributor/param/) cb the callback whose status we want to change.
          ^~
/usr/local/include/event2/buffer.h:220:11: note: did you mean 'buf'?
 * [@param](/bitcoin-bitcoin/contributor/param/) cb the callback whose status we want to change.
          ^~
          buf
In file included from bitcoin-cli.cpp:33:
In file included from ./support/events.h:11:
/usr/local/include/event2/event.h:366:10: warning: parameter 'base' not found in the function declaration [-Wdocumentation] [@param](/bitcoin-bitcoin/contributor/param/) base the event_base structure returned by event_base_new() or
         ^~~~
/usr/local/include/event2/event.h:378:9: warning: parameter 'eb' not found in the function declaration [-Wdocumentation] [@param](/bitcoin-bitcoin/contributor/param/) eb the event_base structure returned by event_base_new()
        ^~
/usr/local/include/event2/event.h:435:11: warning: parameter 'eb' not found in the function declaration [-Wdocumentation] [@param](/bitcoin-bitcoin/contributor/param/) eb the event_base structure returned by event_base_new()
          ^~
/usr/local/include/event2/event.h:436:11: warning: parameter 'flags' not found in the function declaration [-Wdocumentation] [@param](/bitcoin-bitcoin/contributor/param/) flags a bitwise combination of the kinds of events to aggregate
          ^~~~~
/usr/local/include/event2/event.h:447:10: warning: parameter 'eb' not found in the function declaration [-Wdocumentation] [@param](/bitcoin-bitcoin/contributor/param/) eb the event_base structure returned by event_base_new()
         ^~
/usr/local/include/event2/event.h:448:10: warning: parameter 'flags' not found in the function declaration [-Wdocumentation] [@param](/bitcoin-bitcoin/contributor/param/) flags a bitwise combination of the kinds of events to aggregate
         ^~~~~
/usr/local/include/event2/event.h:450:10: warning: parameter 'clear' not found in the function declaration [-Wdocumentation] [@param](/bitcoin-bitcoin/contributor/param/) clear option used to reset the maximum count.
         ^~~~~
/usr/local/include/event2/event.h:672:10: warning: parameter 'cfg' not found in the function declaration [-Wdocumentation] [@param](/bitcoin-bitcoin/contributor/param/) cfg the event configuration object
         ^~~
/usr/local/include/event2/event.h:689:10: warning: parameter 'eb' not found in the function declaration [-Wdocumentation] [@param](/bitcoin-bitcoin/contributor/param/) eb an event_base to be freed
         ^~
/usr/local/include/event2/event.h:782:10: warning: parameter 'eb' not found in the function declaration [-Wdocumentation] [@param](/bitcoin-bitcoin/contributor/param/) eb the event base
         ^~
/usr/local/include/event2/event.h:783:10: warning: parameter 'ev' not found in the function declaration [-Wdocumentation] [@param](/bitcoin-bitcoin/contributor/param/) ev the event
         ^~
/usr/local/include/event2/event.h:817:10: warning: parameter 'eb' not found in the function declaration [-Wdocumentation] [@param](/bitcoin-bitcoin/contributor/param/) eb the event_base structure returned by event_base_new() or
         ^~
/usr/local/include/event2/event.h:819:10: warning: parameter 'flags' not found in the function declaration [-Wdocumentation] [@param](/bitcoin-bitcoin/contributor/param/) flags any combination of EVLOOP_ONCE | EVLOOP_NONBLOCK
         ^~~~~
/usr/local/include/event2/event.h:837:10: warning: parameter 'eb' not found in the function declaration [-Wdocumentation] [@param](/bitcoin-bitcoin/contributor/param/) eb the event_base structure returned by event_init()
         ^~
/usr/local/include/event2/event.h:838:10: warning: parameter 'tv' not found in the function declaration [-Wdocumentation] [@param](/bitcoin-bitcoin/contributor/param/) tv the amount of time after which the loop should terminate,
         ^~

Closing due to controversy