Enable the clang documentation warning. (#15913)

This keeps catching people writing comments that do not match their
code.  Easier to do it via automation than via manual reviews.

Author: bzbarsky-apple

.github/workflows/darwin.yaml

@@ -82,13 +82,10 @@ jobs:
               # enable it for various reasons.  Keep whatever Xcode settings
               # for OTHER_CFLAGS exist by using ${inherited}.
               #
-              # Disable -Wdocumentation because so much of our doxygen is so
-              # broken.  See https://github.com/project-chip/connectedhomeip/issues/6734
-              #
               # Disable -Wmacro-redefined because CHIP_DEVICE_CONFIG_ENABLE_MDNS
               # seems to be unconditionally defined in CHIPDeviceBuildConfig.h,
               # which is apparently being included after CHIPDeviceConfig.h.
-              run: xcodebuild -target "CHIP" -sdk macosx OTHER_CFLAGS='${inherited} -Werror -Wno-documentation -Wno-macro-redefined'
+              run: xcodebuild -target "CHIP" -sdk macosx OTHER_CFLAGS='${inherited} -Werror -Wno-macro-redefined'
               working-directory: src/darwin/Framework
             - name: Clean Build
               run: xcodebuild clean
@@ -117,7 +114,7 @@ jobs:
               run: |
                   mkdir -p /tmp/darwin/framework-tests
                   ../../../out/debug/chip-all-clusters-app > >(tee /tmp/darwin/framework-tests/all-cluster-app.log) 2> >(tee /tmp/darwin/framework-tests/all-cluster-app-err.log >&2) &
-                  xcodebuild test -target "CHIP" -scheme "CHIP Framework Tests" -sdk macosx OTHER_CFLAGS='${inherited} -Werror -Wno-documentation -Wno-incomplete-umbrella' > >(tee /tmp/darwin/framework-tests/darwin-tests.log) 2> >(tee /tmp/darwin/framework-tests/darwin-tests-err.log >&2)
+                  xcodebuild test -target "CHIP" -scheme "CHIP Framework Tests" -sdk macosx OTHER_CFLAGS='${inherited} -Werror -Wno-incomplete-umbrella' > >(tee /tmp/darwin/framework-tests/darwin-tests.log) 2> >(tee /tmp/darwin/framework-tests/darwin-tests-err.log >&2)
               working-directory: src/darwin/Framework
             - name: Uploading log files
               uses: actions/upload-artifact@v2

src/lib/core/CHIPEncoding.h

@@ -33,10 +33,19 @@
 
 #pragma once
 
+// The nlio headers use [inout] instead of [in,out], which makes the clang
+// documentation warning unhappy.  Suppress it for those headers.
+#pragma GCC diagnostic push
+#ifdef __clang__
+#pragma GCC diagnostic ignored "-Wdocumentation"
+#endif // __clang__
+
 #include <nlbyteorder.hpp>
 #include <nlio-byteorder.hpp>
 #include <nlio.hpp>
 
+#pragma GCC diagnostic pop
+
 #include <stdint.h>
 
 namespace chip {