[libc++] Add _LIBCPP_ENABLE_NODISCARD and _LIBCPP_NODISCARD_EXT to allow pre-C++2a [[nodiscard]]
Summary:
The `[[nodiscard]]` attribute is intended to help users find bugs where
function return values are ignored when they shouldn't be. After C++17 the
C++ standard has started to declared such library functions as `[[nodiscard]]`.
However, this application is limited and applies only to dialects after C++17.
Users who want help diagnosing misuses of STL functions may desire a more
liberal application of `[[nodiscard]]`.
For this reason libc++ provides an extension that does just that! The
extension must be enabled by defining `_LIBCPP_ENABLE_NODISCARD`. The extended
applications of `[[nodiscard]]` takes two forms:
1. Backporting `[[nodiscard]]` to entities declared as such by the
standard in newer dialects, but not in the present one.
2. Extended applications of `[[nodiscard]]`, at the libraries discretion,
applied to entities never declared as such by the standard.
Users may also opt-out of additional applications `[[nodiscard]]` using
additional macros.
Applications of the first form, which backport `[[nodiscard]]` from a newer
dialect may be disabled using macros specific to the dialect it was added. For
example `_LIBCPP_DISABLE_NODISCARD_AFTER_CXX17`.
Applications of the second form, which are pure extensions, may be disabled
by defining `_LIBCPP_DISABLE_NODISCARD_EXT`.
This patch was originally written by me (Roman Lebedev),
then but then reworked by Eric Fiselier.
Reviewers: mclow.lists, thakis, EricWF
Reviewed By: thakis, EricWF
Subscribers: llvm-commits, mclow.lists, lebedev.ri, EricWF, rjmccall, Quuxplusone, cfe-commits, christof
Differential Revision: https://reviews.llvm.org/D45179
llvm-svn: 342808
Cr-Mirrored-From: sso://chromium.googlesource.com/_direct/external/github.com/llvm/llvm-project
Cr-Mirrored-Commit: c65d39a46473cad3ff87966619f74aa7ea1a44eb
diff --git a/docs/UsingLibcxx.rst b/docs/UsingLibcxx.rst
index e10a27c..993c8d7 100644
--- a/docs/UsingLibcxx.rst
+++ b/docs/UsingLibcxx.rst
@@ -226,6 +226,21 @@
replacement scenarios from working, e.g. replacing `operator new` and
expecting a non-replaced `operator new[]` to call the replaced `operator new`.
+**_LIBCPP_ENABLE_NODISCARD**:
+ Allow the library to add ``[[nodiscard]]`` attributes to entities not specified
+ as ``[[nodiscard]]`` by the current language dialect. This includes
+ backporting applications of ``[[nodiscard]]`` from newer dialects and
+ additional extended applications at the discretion of the library. All
+ additional applications of ``[[nodiscard]]`` are disabled by default.
+ See :ref:`Extended Applications of [[nodiscard]] <nodiscard extension>` for
+ more information.
+
+**_LIBCPP_DISABLE_NODISCARD_EXT**:
+ This macro prevents the library from applying ``[[nodiscard]]`` to entities
+ purely as an extension. See :ref:`Extended Applications of [[nodiscard]] <nodiscard extension>`
+ for more information.
+
+
C++17 Specific Configuration Macros
-----------------------------------
**_LIBCPP_ENABLE_CXX17_REMOVED_FEATURES**:
@@ -238,3 +253,58 @@
**_LIBCPP_ENABLE_CXX17_REMOVED_AUTO_PTR**:
This macro is used to re-enable `std::auto_ptr` in C++17.
+
+C++2a Specific Configuration Macros:
+------------------------------------
+**_LIBCPP_DISABLE_NODISCARD_AFTER_CXX17**:
+ This macro can be used to disable diagnostics emitted from functions marked
+ ``[[nodiscard]]`` in dialects after C++17. See :ref:`Extended Applications of [[nodiscard]] <nodiscard extension>`
+ for more information.
+
+
+Libc++ Extensions
+=================
+
+This section documents various extensions provided by libc++, how they're
+provided, and any information regarding how to use them.
+
+.. _nodiscard extension:
+
+Extended applications of ``[[nodiscard]]``
+------------------------------------------
+
+The ``[[nodiscard]]`` attribute is intended to help users find bugs where
+function return values are ignored when they shouldn't be. After C++17 the
+C++ standard has started to declared such library functions as ``[[nodiscard]]``.
+However, this application is limited and applies only to dialects after C++17.
+Users who want help diagnosing misuses of STL functions may desire a more
+liberal application of ``[[nodiscard]]``.
+
+For this reason libc++ provides an extension that does just that! The
+extension must be enabled by defining ``_LIBCPP_ENABLE_NODISCARD``. The extended
+applications of ``[[nodiscard]]`` takes two forms:
+
+1. Backporting ``[[nodiscard]]`` to entities declared as such by the
+ standard in newer dialects, but not in the present one.
+
+2. Extended applications of ``[[nodiscard]]``, at the libraries discretion,
+ applied to entities never declared as such by the standard.
+
+Users may also opt-out of additional applications ``[[nodiscard]]`` using
+additional macros.
+
+Applications of the first form, which backport ``[[nodiscard]]`` from a newer
+dialect may be disabled using macros specific to the dialect it was added. For
+example ``_LIBCPP_DISABLE_NODISCARD_AFTER_CXX17``.
+
+Applications of the second form, which are pure extensions, may be disabled
+by defining ``_LIBCPP_DISABLE_NODISCARD_EXT``.
+
+
+Entities declared with ``_LIBCPP_NODISCARD_EXT``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This section lists all extended applications of ``[[nodiscard]]`` to entities
+which no dialect declares as such (See the second form described above).
+
+* ``get_temporary_buffer``