Turning on warnings about documentation comments.

Given that the project builds with -Werror, the documentation comment
warning has been forced to stay a warning via -Wno-error-documentation.
When the project is free of documentation warnings, this should be
removed.

Warnings about documentation comments containing @deprecated but the
actual declaration not having a deprecated attribute have been disabled
via -Wno-documentation-deprecated-sync. Turning this on and fixing the
warnings will result in a cascade of new warnings relating to using
deprecated APIs.

Issue: PLCR-543
Fixing the bulk of the documentation warnings.

This leaves a handful of warnings about using '@sa @ref async_safety'.
Clang thinks that the '@sa' command has an empty paragraph in this
case, but it appears to be a false positive and a bug in Clang.

Issue: PLCR-543