bsla_annotations.h

Go to the documentation of this file.

/// @file bsla_annotations.h
///
/// The content of this file has been pre-processed for Doxygen.
///
 
 
// bsla_annotations.h                                                 -*-C++-*-
#ifndef INCLUDED_BSLA_ANNOTATIONS
#define INCLUDED_BSLA_ANNOTATIONS
 
#include <bsls_ident.h>
BSLS_IDENT("$Id: $")
 
/// @defgroup bsla_annotations bsla_annotations
/// @brief  Provide support for compiler annotations for compile-time safety.
/// @addtogroup bsl
/// @{
/// @addtogroup bsla
/// @{
/// @addtogroup bsla_annotations
/// @{
///
/// <h1> Outline </h1>
/// * <a href="#bsla_annotations-purpose"> Purpose</a>
/// * <a href="#bsla_annotations-macros"> Macros </a>
/// * <a href="#bsla_annotations-description"> Description </a>
///   * <a href="#bsla_annotations-macro-reference"> Macro Reference </a>
///   * <a href="#bsla_annotations-usage"> Usage </a>
///
/// # Purpose {#bsla_annotations-purpose}
/// Provide support for compiler annotations for compile-time safety.
///
/// # Macros {#bsla_annotations-macros}
///
/// -  BSLA_DEPRECATED: warn if annotated (deprecated) entity is used
/// -  BSLA_ERROR(QUOTED_MESSAGE): emit error message and fail compilation
/// -  BSLA_FALLTHROUGH: do not warn if `switch` `case` falls through
/// -  BSLA_FORMAT(FMT_IDX): validate `printf`-style format spec in `n`th argument
/// -  BSLA_MAYBE_UNUSED: suppress compiler warnings on unused entities
/// -  BSLA_NODISCARD: warn if annotated function result is not used
/// -  BSLA_NONNULLARG(...): warn if indexed arguments are NULL
/// -  BSLA_NONNULLARGS: warn if any arguments are NULL
/// -  BSLA_NORETURN: issue a compiler warning if function returns normally
/// -  BSLA_NULLTERMINATED:            warn if last argument is non-NULL
/// -  BSLA_NULLTERMINATEDAT(ARG_IDX): warn if argument at `ARG_IDX` is non-NULL
/// -  BSLA_PRINTF(FMTIDX, STARTIDX): validate `printf` format and arguments
/// -  BSLA_SCANF(FMTIDX, STARTIDX): validate `scanf` format and arguments
/// -  BSLA_UNUSED: do not warn if annotated entity is unused
/// -  BSLA_USED: emit annotated entity even if not referenced
/// -  BSLA_WARNING(QUOTED_MESSAGE): emit warning message during compilation
/// -  BSLA_DEPRECATED_IS_ACTIVE:       defined if `BSLA_DEPRECATED`     is active
/// -  BSLA_ERROR_IS_ACTIVE:            defined if `BSLA_ERROR`          is active
/// -  BSLA_FALLTHROUGH_IS_ACTIVE:      defined if `BSLA_FALLTHROUGH`    is active
/// -  BSLA_FORMAT_IS_ACTIVE:           defined if `BSLA_FORMAT`         is active
/// -  BSLA_MAYBE_UNUSED_IS_ACTIVE:     defined if `BSLA_MAYBE_UNUSED`   is active
/// -  BSLA_NODISCARD_IS_ACTIVE:        defined if `BSLA_NODISCARD`      is active
/// -  BSLA_NONNULLARG_IS_ACTIVE:       defined if `BSLA_NONNULLARG`     is active
/// -  BSLA_NONNULLARGS_IS_ACTIVE:      defined if `BSLA_NONNULLARGS`    is active
/// -  BSLA_NORETURN_IS_ACTIVE:         defined if `BSLA_NORETURN`       is active
/// -  BSLA_NULLTERMINATED_IS_ACTIVE:   defined if `BSLA_NULLTERMINATED` is active
/// -  BSLA_NULLTERMINATEDAT_IS_ACTIVE: defined if `BSLA_NULLTERMINATEDAT`  active
/// -  BSLA_PRINTF_IS_ACTIVE:           defined if `BSLA_PRINTF`         is active
/// -  BSLA_SCANF_IS_ACTIVE:            defined if `BSLA_SCANF`          is active
/// -  BSLA_UNUSED_IS_ACTIVE:           defined if `BSLA_UNUSED`         is active
/// -  BSLA_USED_IS_ACTIVE:             defined if `BSLA_USED`           is active
/// -  BSLA_WARNING_IS_ACTIVE:          defined if `BSLA_WARNING`        is active
///
/// # Description {#bsla_annotations-description}
/// 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.
///
/// For the most part, these compile-time annotations are supported only when
/// the `BSLS_PLATFORM_CMP_GNU` or `BSLS_PLATFORM_CMP_CLANG` preprocessor macros
/// are defined.  Other compilers may implement a few annotations, but the
/// macros should be expected to work only with compilers for which
/// `BSLS_PLATFORM_CMP_GNU` or `BSLS_PLATFORM_CMP_CLANG` is defined.
///
/// ## Macro Reference {#bsla_annotations-macro-reference}
///
///
///  `BSLA_DEPRECATED`:
///      This annotation will, when used, cause a compile-time warning if the
///      so-annotated function, variable, or type is used anywhere within the
///      source file.  This is useful, for example, when identifying functions
///      that are expected to be removed in a future version of a library.  The
///      warning includes the location of the declaration of the deprecated
///      entity to enable users to find further information about the
///      deprecation, or what they should use instead.
/// 
///  `BSLA_ERROR(QUOTED_MESSAGE)`:
///      This annotation, when used, will cause a compile-time error when a call
///      to the so-annotated function is not removed through dead-code
///      elimination or other optimizations.  While it is possible to leave the
///      function undefined, thus incurring a link-time failure, with the use of
///      this macro the invalid call will be diagnosed earlier (i.e., at compile
///      time), and the diagnostic will include the location of the function
///      call.  The message `QUOTED_MESSAGE`, which should be a double-quoted
///      string, will appear in the error message.
/// 
///  `BSLA_FALLTHROUGH`:
///      This annotation should be placed in a `case` clause as the last
///      statement within a flow of control that is expected to allow control to
///      fall through instead of ending with a `break`, `continue`, or `return`.
///      This will prevent compilers from warning about fall-through.  The
///      `BSLA_FALLTHROUGH` must be followed by a semicolon and may be nested
///      within blocks, `if`s, or `else`s.
/// 
///  `BSLA_FORMAT(FMT_IDX)`:
///      This annotation specifies that the so-annotated function takes an
///      argument that is a valid format string for a `printf`-style function
///      and returns a format string that is consistent with that format.  This
///      allows format strings manipulated by translation functions to be
///      checked against arguments.  Without this annotation, attempting to
///      manipulate the format string via this kind of function might generate
///      warnings about non-literal formats, or fail to generate warnings about
///      mismatched arguments.
/// 
///  `BSLA_MAYBE_UNUSED`:
///      This annotation indicates that the so-annotated function, variable, or
///      type is possibly unused and the compiler should not generate a warning
///      for the unused identifier.
/// 
///  `BSLA_NODISCARD`:
///      This annotation causes a warning to be emitted if the caller of a
///      so-annotated function does not use its return value.  This is useful
///      for functions where not checking the result is either a security
///      problem or always a bug, such as with the `realloc` function.
/// 
///  `BSLA_NONNULLARGS`:
///      This annotation indicates that a compiler warning is to be issued if
///      any of the pointer arguments to this function are passed null.
/// 
///  `BSLA_NONNULLARG(...)`:
///      This annotation, passed a variable-length list of positive integers,
///      indicates that a compiler warning is to be issued if null is passed to
///      a pointer argument at any of the specified indices, where the first
///      argument of the annotated function has an index of 1.
/// 
///  `BSLA_NORETURN`:
///      This annotation is used to tell the compiler that a specified function
///      will not return in a normal fashion.  The function can still exit via
///      other means such as throwing an exception or aborting the process.
/// 
///  `BSLA_NULLTERMINATED`:
///      This annotation on a variadic macro indicates that a warning should be
///      issued unless the last argument to the function is explicitly `NULL`.
/// 
///  `BSLA_NULLTERMINATEDAT(ARG_IDX)`:
///      This annotation on a variadic function indicates that a warning should
///      be issued unless the argument at `ARG_IDX` is `NULL`, where `ARG_IDX`
///      is the number of arguments from the last, the last argument having
///      `ARG_IDX == 0`.  Thus, `BSLA_NULLTERMINATED` is equivalent to
///      `BSLA_NULLTERMINATEDAT(0)`.
/// 
///  `BSLA_PRINTF(FMTIDX, STARTIDX)`:
///      This annotation instructs the compiler to perform additional
///      compile-time checks on so-annotated functions that take `printf`-style
///      arguments, which should be type-checked against a format string.  The
///      `FMTIDX` parameter is the one-based index to the `const char *` format
///      string.  The `STARTIDX` parameter is the one-based index to the first
///      variable argument to type-check against that format string.  For
///      example:
/// @code
/// extern int my_printf(void *obj, const char *format, ...) BSLA_PRINTF(2, 3);
/// @endcode
/// 
///  `BSLA_SCANF(FMTIDX, STARTIDX)`:
///      This annotation instructs the compiler to perform additional checks on
///      so-annotated functions that take `scanf`-style arguments, which should
///      be type-checked against a format string.
/// 
///      The `FMTIDX` parameter is the one-based index to the `const` format
///      string.  The `STARTIDX` parameter is the one-based index to the first
///      variable argument to type-check against that format string.  For
///      example:
/// @code
/// extern int my_scanf(void *obj, const char *format, ...) BSLA_SCANF(2, 3);
/// @endcode
/// 
///  `BSLA_UNREACHABLE`:
///      This annotation will, when used, indicate that a given statement in a
///      code path is intended to be unreachable, causing compilers, where
///      supported, to issue warnings if there is actually a way that the code
///      can be reached.  Note that the behavior is undefined if control
///      actually reaches a `BSLA_UNREACHABLE` statement.
/// 
///  `BSLA_UNUSED`:
///      This annotation indicates that the so-annotated function, variable, or
///      type is possibly unused and the compiler should not generate a warning
///      for the unused identifier.
/// 
///  `BSLA_USED`:
///      This annotation indicates that the so-annotated function, variable, or
///      type must be emitted even if it appears that the variable is not
///      referenced.
/// 
///  `BSLA_WARNING(QUOTED_MESSAGE)`:
///      This annotation, when used, will cause a compile-time warning
///      containing the specified `QUOTED_MESSAGE`, which must be a string
///      contained in double quotes, when a call to the so-annotated function is
///      not removed through dead-code elimination or other optimizations.
///      While it is possible to leave the function undefined, thus incurring a
///      link-time failure, with the use of this macro the invalid call will be
///      diagnosed earlier (i.e., at compile time), and the diagnostic will
///      include the location of the function call.
/// 
///  `BSLA_DEPRECATED_IS_ACTIVE`
///  `BSLA_ERROR_IS_ACTIVE`
///  `BSLA_FALLTHROUGH_IS_ACTIVE`
///  `BSLA_FORMAT_IS_ACTIVE`
///  `BSLA_MAYBE_UNUSED_IS_ACTIVE`
///  `BSLA_NODISCARD_IS_ACTIVE`
///  `BSLA_NONNULLARG_IS_ACTIVE`
///  `BSLS_NONNULLARGS_IS_ACTIVE`
///  `BSLA_NORETURN_IS_ACTIVE`
///  `BSLA_NULLTERMINATED_IS_ACTIVE`
///  `BSLA_NULLTERMINATEDAT_IS_ACTIVE`
///  `BSLA_PRINTF_IS_ACTIVE`
///  `BSLA_SCANF_IS_ACTIVE`
///  `BSLA_UNREACHABLE_IS_ACTIVE`
///  `BSLA_UNUSED_IS_ACTIVE`
///  `BSLA_USED_IS_ACTIVE`
///  `BSLA_WARNING_IS_ACTIVE`:
///      For each `BSLA_{X}` macro, there is a `BSLA_{X}_IS_ACTIVE` macro that
///      is defined only if `BSLA_{X}` expands to something and has its
///      documented effects.
///
/// ## Usage {#bsla_annotations-usage}
///
///
/// See the other `bsla` components for usage examples for the macros offered
/// (transitively) by this component.
/// @}
/** @} */
/** @} */
 
/** @addtogroup bsl
 * @{
 */
/** @addtogroup bsla
 * @{
 */
/** @addtogroup bsla_annotations
 * @{
 */
 
#include <bsla_deprecated.h>
#include <bsla_error.h>
#include <bsla_fallthrough.h>
#include <bsla_format.h>
#include <bsla_maybeunused.h>
#include <bsla_nodiscard.h>
#include <bsla_nonnullarg.h>
#include <bsla_noreturn.h>
#include <bsla_nullterminated.h>
#include <bsla_printf.h>
#include <bsla_scanf.h>
#include <bsla_unreachable.h>
#include <bsla_unused.h>
#include <bsla_used.h>
#include <bsla_warning.h>
 
// BDE_VERIFY pragma: re-export <bsla_deprecated.h>
// BDE_VERIFY pragma: re-export <bsla_error.h>
// BDE_VERIFY pragma: re-export <bsla_fallthrough.h>
// BDE_VERIFY pragma: re-export <bsla_format.h>
// BDE_VERIFY pragma: re-export <bsla_maybeunused.h>
// BDE_VERIFY pragma: re-export <bsla_nodiscard.h>
// BDE_VERIFY pragma: re-export <bsla_nonnullarg.h>
// BDE_VERIFY pragma: re-export <bsla_noreturn.h>
// BDE_VERIFY pragma: re-export <bsla_nullterminated.h>
// BDE_VERIFY pragma: re-export <bsla_printf.h>
// BDE_VERIFY pragma: re-export <bsla_scanf.h>
// BDE_VERIFY pragma: re-export <bsla_unreachable.h>
// BDE_VERIFY pragma: re-export <bsla_unused.h>
// BDE_VERIFY pragma: re-export <bsla_used.h>
// BDE_VERIFY pragma: re-export <bsla_warning.h>
 
#endif
 
// ----------------------------------------------------------------------------
// Copyright 2019 Bloomberg Finance L.P.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
// ----------------------------- END-OF-FILE ----------------------------------
 
/** @} */
/** @} */
/** @} */