29/// * <a href="#bsla_fallthrough-example-1-suppressing-fall-through-warnings-in-a-switch-statement"> Example 1: Suppressing Fall-Through Warnings in a switch Statement </a>
30///
31/// # Purpose {#bsla_fallthrough-purpose}
32/// Provide a macro to suppress warnings on `switch` fall-throughs.
33///
34/// # Macros {#bsla_fallthrough-macros}
35///
36/// - BSLA_FALLTHROUGH: do not warn if `switch` `case` falls through
37/// - BSLA_FALLTHROUGH_IS_ACTIVE: defined if `BSLA_FALLTHROUGH` is active
51/// This annotation should be placed in a `case` clause as the last
52/// statement within a flow of control that is expected to allow control to
53/// fall through instead of ending with a `break`, `continue`, or `return`.
54/// This will prevent compilers from warning about fall-through. The
55/// `BSLA_FALLTHROUGH` must be followed by a semicolon and may be nested
56/// within blocks, `if`s, or `else`s.
57///
58/// `BSLA_FALLTHROUGH_IS_ACTIVE`:
59/// The macro `BSLA_FALLTHROUGH_IS_ACTIVE` is defined if `BSLA_FALLTHROUGH`
60/// expands to something with the desired effect; otherwise
61/// `BSLA_FALLTHROUGH_IS_ACTIVE` is not defined and `BSLA_FALLTHROUGH`
62/// expands to nothing.
63///
64/// ## Usage {#bsla_fallthrough-usage}
65///
66///
67/// This section illustrates intended use of this component.
68///
69/// ### Example 1: Suppressing Fall-Through Warnings in a switch Statement {#bsla_fallthrough-example-1-suppressing-fall-through-warnings-in-a-switch-statement}
70///
71///
72/// First, we define a function:
73/// @code
74/// int usageFunction(int jj)
75/// // Demonstrate the usage of 'BSLA_FALLTHROUGH', read the specified
76/// // 'jj'.
77/// {
78/// for (int ii = 0; ii < 5; ++ii) {
79/// @endcode
80/// Then, we have a `switch` in the function:
81/// @code
82/// switch (ii) {
83/// case 0: {
84/// printf("%d\n", jj - 3);
85/// @endcode
86/// Next, we see that `BSLA_FALLTHROUGH;` as the last statement in a `case`
87/// block before falling through silences the fall-through warning from the
88/// compiler:
89/// @code
90/// BSLA_FALLTHROUGH;
91/// }
92/// case 1:
93/// @endcode
94/// Then, we see this also works on `case`s that don't have a `{}` block:
95/// @code
96/// jj -= 6;
97/// printf("%d\n", jj);
98/// BSLA_FALLTHROUGH;
99/// case 2: {
100/// if (jj > 4) {
101/// printf("%d\n", jj + 10);
102/// @endcode
103/// Next, we see that a `BSLA_FALLTHROUGH;` works within an `if` block, provided
104/// that it's in the last statement in the flow of control before falling
105/// through:
106/// @code
107/// BSLA_FALLTHROUGH;
108/// }
109/// else {
110/// return 0; // RETURN
111/// }
112/// }
113/// case 3: {
114/// if (jj > 4) {
115/// continue;
116/// }
117/// else {
118/// printf("%d\n", ++jj);
119/// @endcode
120/// Now, we see that a `BSLA_FALLTHROUGH;` can also occur as the last statement
121/// in an `else` block:
122/// @code
123/// BSLA_FALLTHROUGH;
124/// }
125/// }
126/// default: {
127/// return 1; // RETURN
128/// } break;
129/// }
130/// }
131///
132/// return -7;
133/// }
134/// @endcode
135/// Finally, we see that if we compile when `BSLA_FALLTHROUGH_IS_ACTIVE` is set,
1.9.8