29/// * <a href="#bsla_error-example-1-flagging-a-function-for-a-compile-failure-and-message-if-used"> Example 1: Flagging a Function for a Compile Failure and Message if Used </a>
30///
31/// # Purpose {#bsla_error-purpose}
32/// Provide a macro to emit an error message when a function is called.
33///
34/// # Macros {#bsla_error-macros}
35///
36/// - BSLA_ERROR(QUOTED_MESSAGE): emit error message and fail compilation
37/// - BSLA_ERROR_IS_ACTIVE: defined if `BSLA_ERROR` is active
38///
39/// @see bsla_annotations
40///
41/// # Description {#bsla_error-description}
42/// This component provides a preprocessor macro that flags a
43/// function such that the compile will fail with an error message when the
44/// function is called. On platforms where the appropriate attribute is not
51/// This annotation, when used, will cause compilation to fail with an
52/// error message when a call to the so-annotated function is not removed
53/// through dead-code elimination or other optimizations. While it is
54/// possible to leave the function undefined, thus incurring a link-time
55/// failure, with the use of this macro the invalid call will be diagnosed
56/// earlier (i.e., at compile time), and the diagnostic will include the
57/// location of the function call. The message `QUOTED_MESSAGE`, which
58/// should be a double-quoted string, will appear in the error message.
59///
60/// `BSLA_ERROR_IS_ACTIVE`:
61/// The macro `BSLA_ERROR_IS_ACTIVE` is defined if `BSLA_ERROR` expands to
62/// something with the desired effect; otherwise `BSLA_ERROR_IS_ACTIVE` is
63/// not defined and `BSLA_ERROR` expands to nothing.
64///
65/// ## Usage {#bsla_error-usage}
66///
67///
68/// This section illustrates intended use of this component.
69///
70/// ### Example 1: Flagging a Function for a Compile Failure and Message if Used {#bsla_error-example-1-flagging-a-function-for-a-compile-failure-and-message-if-used}
71///
72///
73/// First, we declare and define a function annotated with `BSLA_ERROR`. Note
74/// that the argument to `BSLA_ERROR` must be a quoted string:
1.9.8