bsla.h

Go to the documentation of this file.

/// @file bsla.h
///
///
/// @defgroup bsla Package bsla
/// @brief  Basic Standard Library Annotations (bsla)
/// @addtogroup bsl
/// @{
/// @addtogroup bsla
/// @{
/// * <a href="#bsla-purpose"> Purpose</a>
/// * <a href="#bsla-mnemonic"> Mnemonic </a>
/// * <a href="#bsla-description"> Description </a>
///   * <a href="#bsla-hierarchical-synopsis"> Hierarchical Synopsis </a>
///   * <a href="#bsla-component-synopsis"> Component Synopsis </a>
///   * <a href="#bsla-component-overview"> Component Overview </a>
///     * <a href="#bsla-bsla_annotations"> bsla_annotations </a>
///     * <a href="#bsla-bsla_deprecated"> bsla_deprecated </a>
///     * <a href="#bsla-bsla_error"> bsla_error </a>
///     * <a href="#bsla-bsla_fallthrough"> bsla_fallthrough </a>
///     * <a href="#bsla-bsla_format"> bsla_format </a>
///     * <a href="#bsla-bsla_maybeunused"> bsla_maybeunused </a>
///     * <a href="#bsla-bsla_nodiscard"> bsla_nodiscard </a>
///     * <a href="#bsla-bsla_nonnullarg"> bsla_nonnullarg </a>
///     * <a href="#bsla-bsla_noreturn"> bsla_noreturn </a>
///     * <a href="#bsla-bsla_nullterminated"> bsla_nullterminated </a>
///     * <a href="#bsla-bsla_printf"> bsla_printf </a>
///     * <a href="#bsla-bsla_scanf"> bsla_scanf </a>
///     * <a href="#bsla-bsla_unreachable"> bsla_unreachable </a>
///     * <a href="#bsla-bsla_unused"> bsla_unused </a>
///     * <a href="#bsla-bsla_used"> bsla_used </a>
///     * <a href="#bsla-bsla_warning"> bsla_warning </a>
///
/// # Purpose {#bsla-purpose}
/// Provide macros for portable use of compiler annotations.
///
/// # Mnemonic {#bsla-mnemonic}
/// Basic Standard Library Annotations (bsla)
///
/// # Description {#bsla-description}
/// The 'bsla' package provides a variety of macros that expand to
/// annotations to provide hints to the compiler, to suppress or emit compiler
/// warnings or errors.
///
/// The annotations themselves are not supported on all compilers, and sometimes
/// different annotations are required for different compilers to have a given
/// effect.  The macros provided in this package either expand to the correct
/// annotation for the current compiler, or, if the compiler does not support any
/// form of the given annotation, the macros expand to nothing.
///
/// For every macro, 'BSLA_{X}', there is a corresponding macro,
/// 'BSLA_{X}_IS_ACTIVE', which is always defined to an integer, and expands to 0
/// if 'BSLA_{X}' expands to nothing and 1 if 'BSLA_{X}' expands to an annotation
/// and the annotation works.  There are situations where compilers will
/// "tolerate" an annotation -- the annotation won't be reported as a syntax
/// error, but it will have no effect.  In those cases, 'BSLA_{X}' will expand to
/// nothing and 'BSLA_{X}_IS_ACTIVE' will be 0.
///
/// ## Hierarchical Synopsis {#bsla-hierarchical-synopsis}
///
/// The 'bsla' package currently has 16 components having 3 levels of physical
/// dependency.  The list below shows the hierarchical ordering of the components.
/// The order of components within each level is not architecturally significant,
/// just alphabetical.
/// @code
///  3. bsla_annotations
///
///  2. bsla_used
///
///  1. bsla_deprecated
///     bsla_error
///     bsla_fallthrough
///     bsla_format
///     bsla_maybeunused
///     bsla_nodiscard
///     bsla_nonnullarg
///     bsla_noreturn
///     bsla_nullterminated
///     bsla_printf
///     bsla_scanf
///     bsla_unreachable
///     bsla_unused                                         !DEPRECATED!
///     bsla_warning
/// @endcode
///
/// ## Component Synopsis {#bsla-component-synopsis}
///
///  @ref bsla_annotations :
///       Provide support for compiler annotations for compile-time safety.
/// 
///  @ref bsla_deprecated :
///       Provide compiler-hint macros to indicate deprecated entities.
/// 
///  @ref bsla_error :
///       Provide a macro to emit an error message when a function is called.
/// 
///  @ref bsla_fallthrough :
///       Provide a macro to suppress warnings on `switch` fall-throughs.
/// 
///  @ref bsla_format :
///       Provide a macro to indicate that a return value is a format string.
/// 
///  @ref bsla_maybeunused :
///       Provide a macro to suppress "unused" warnings.
/// 
///  @ref bsla_nodiscard :
///       Provide a macro for warning about ignored function results.
/// 
///  @ref bsla_nonnullarg :
///       Provide macros to hint at null arguments to functions.
/// 
///  @ref bsla_noreturn :
///       Provide a macro to issue a compiler warning if a function returns.
/// 
///  @ref bsla_nullterminated :
///       Provide macros for use with `NULL`-terminated variadic functions.
/// 
///  @ref bsla_printf :
///       Provide a macro to indicate `printf`-style arguments.
/// 
///  @ref bsla_scanf :
///       Provide a macro for checking `scanf`-style format strings.
/// 
///  @ref bsla_unreachable :
///       Provide a compiler-hint macro to indicate unreachable code.
/// 
///  @ref bsla_unused :                                         !DEPRECATED!
///       Provide a macro to suppress "unused" warnings.
/// 
///  @ref bsla_used :
///       Provide a macro to prevent elision of unused entities.
/// 
///  @ref bsla_warning :
///       Provide a macro to emit a warning when a function is called.
///
/// ## Component Overview {#bsla-component-overview}
///
/// This section provides a brief introduction to some of the components in the
/// 'bsla' package.  See the documentation in each component for full details.
///
/// ### bsla_annotations {#bsla-bsla_annotations}
///
/// This component exists to provide a single component whose header can be
/// included to transitively include all of the annotation macros defined in the
/// 'bsla' package.  The macros that are transitively included by this component
/// correspond to various compiler features, and can be used to annotate code for
/// specific compile-time safety checks.
///
/// ### bsla_deprecated {#bsla-bsla_deprecated}
///
/// This component provides a preprocessor macro that hints to the compile that a
/// function, variable, or type is deprecated.
///
/// ### bsla_error {#bsla-bsla_error}
///
/// This component provides a preprocessor macro that flags a function such that a
/// compiler error will occur when the function is called.  On platforms where the
/// appropriate attribute is not supported, the macro expands to nothing.
///
/// ### bsla_fallthrough {#bsla-bsla_fallthrough}
///
/// This component provides a preprocessor macro that suppresses compiler warnings
/// about flow of control fall-through from one 'case' or 'default' of a 'switch'
/// statement to another.  On compilers where the appropriate attribute is not
/// supported, the macro expands to nothing.
///
/// ### bsla_format {#bsla-bsla_format}
///
/// This component provides a preprocessor macro to indicate that an indexed
/// argument of a function is a 'printf'-style format specification, and that the
/// function will return a 'printf'-style format string with an equivalent
/// specification.
///
/// ### bsla_maybeunused {#bsla-bsla_maybeunused}
///
/// This component provides a preprocessor macro that will suppress "unused"
/// warnings on a locally defined function, type, or variable that is not used.
///
/// ### bsla_nodiscard {#bsla-bsla_nodiscard}
///
/// This component provides a preprocessor macro that annotates a function such
/// that a compiler warning will be generated if the return value of the function
/// is ignored.
///
/// ### bsla_nonnullarg {#bsla-bsla_nonnullarg}
///
/// This component provides preprocessor macros that define compiler-specific
/// compile-time annotations.  These macros instruct the compiler to warn if null
/// is passed to certain arguments to a function, or, on platforms where the
/// feature is not supported, expand to nothing.
///
/// ### bsla_noreturn {#bsla-bsla_noreturn}
///
/// This component provides a preprocessor macro that annotates a function as
/// never returning, resulting in a compiler warning if a path of control exists
/// such that the function does return.
///
/// ### bsla_nullterminated {#bsla-bsla_nullterminated}
///
/// This component provides preprocessor macros to indicate that a variadic
/// function's arguments are terminated by a 'NULL' value, or, in the case of
/// 'BSLA_NULLTERMINATEDAT', by a 'NULL' value at a certain index.  Note that the
/// terminating 'NULL' must actually be 'NULL'; passing 0 in it's place will
/// result in a warning.
///
/// ### bsla_printf {#bsla-bsla_printf}
///
/// This component provides a preprocessor macro that allows the designation of a
/// given function argument as a 'printf'-style format string, and arguments
/// starting at a certain index in the argument list to be formatted according to
/// that string.
///
/// ### bsla_scanf {#bsla-bsla_scanf}
///
/// This component provides a preprocessor macro that indicates that one of the
/// arguments to a function is a 'scanf'-style format string, and that the
/// arguments starting at a certain index are to be checked for compatibility with
/// that format string.
///
/// ### bsla_unreachable {#bsla-bsla_unreachable}
///
/// This component provides a preprocessor macro that hints to the compile that a
/// statement in the code is intended to be unreachable.
///
/// ### bsla_unused {#bsla-bsla_unused}
///
/// This component provides a preprocessor macro that will suppress "unused"
/// warnings on a locally defined function, type, or variable that is not used.
///
/// ### bsla_used {#bsla-bsla_used}
///
/// This component provides a preprocessor macro that will guarantee the emission
/// of a local function, type, or variable whether it is used or not.
///
/// ### bsla_warning {#bsla-bsla_warning}
///
/// This component provides a macro that indicates that a compiler warning should
/// be emitted when a given function is called.
///
/// @}
/** @} */