1 files changed, 25 insertions, 0 deletions
diff --git a/docs/UsersManual.rst b/docs/UsersManual.rst
index 97784f1b1b..3dc07aba90 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
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^