1 files changed, 38 insertions, 0 deletions
diff --git a/docs/UsersManual.rst b/docs/UsersManual.rst
index 6cc8361..3dc07ab 100644
--- a/docs/UsersManual.rst
+++ b/docs/UsersManual.rst
@@ -652,6 +652,31 @@ supports the GCC pragma, Clang and GCC do not support the exact same set
 of warnings, so even when using GCC compatible #pragmas there is no
 guarantee that they will have identical behaviour on both compilers.
 
+In addition to controlling warnings and errors generated by the compiler, it is
+possible to generate custom warning and error messages through the following
+pragmas:
+
+.. code-block:: c
+
+  // The following will produce warning messages
+  #pragma message "some diagnostic message"
+  #pragma GCC warning "TODO: replace deprecated feature"
+
+  // The following will produce an error message
+  #pragma GCC error "Not supported"
+
+These pragmas operate similarly to the ``#warning`` and ``#error`` preprocessor
+directives, except that they may also be embedded into preprocessor macros via
+the C99 ``_Pragma`` operator, for example:
+
+.. code-block:: c
+
+  #define STR(X) #X
+  #define DEFER(M,...) M(__VA_ARGS__)
+  #define CUSTOM_ERROR(X) _Pragma(STR(GCC error(X " at line " DEFER(STR,__LINE__))))
+
+  CUSTOM_ERROR("Feature not available");
+
 Controlling Diagnostics in System Headers
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -1005,6 +1030,19 @@ below. If multiple flags are present, the last one is used.
 
   Generate complete debug info.
 
+Comment Parsing Options
+--------------------------
+
+Clang parses Doxygen and non-Doxygen style documentation comments and attaches
+them to the appropriate declaration nodes.  By default, it only parses
+Doxygen-style comments and ignores ordinary comments starting with ``//`` and
+``/*``.
+
+.. option:: -fparse-all-comments
+
+  Parse all comments as documentation comments (including ordinary comments
+  starting with ``//`` and ``/*``).
+
 .. _c:
 
 C Language Features