[libcxx-commits] [libcxx] 2684a09 - [libc++] Document guidelines for applying [[nodiscard]] (#84000)

[via libcxx-commits]

Author: Nikolas Klauser
Date: 2024-03-29T19:33:46+01:00
New Revision: 2684a0966d5c84071c811c68ec25e41a0beb26f4

URL: https://github.com/llvm/llvm-project/commit/2684a0966d5c84071c811c68ec25e41a0beb26f4
DIFF: https://github.com/llvm/llvm-project/commit/2684a0966d5c84071c811c68ec25e41a0beb26f4.diff

LOG: [libc++] Document guidelines for applying [[nodiscard]] (#84000)

We've been applying ``[[nodiscard]]`` more liberally recently, but we
don't have any documented guidance on when it's correct to add it. This
patch adds that guidance. Follow-up patches will gradually apply it to
the code base.

Added: 
    libcxx/docs/DesignDocs/NodiscardPolicy.rst

Modified: 
    libcxx/docs/index.rst

Removed: 
    


################################################################################
diff  --git a/libcxx/docs/DesignDocs/NodiscardPolicy.rst b/libcxx/docs/DesignDocs/NodiscardPolicy.rst
new file mode 100644
index 00000000000000..afbb18b0096d73
--- /dev/null
+++ b/libcxx/docs/DesignDocs/NodiscardPolicy.rst
@@ -0,0 +1,42 @@
+===================================================
+Guidelines for applying ``[[nodiscard]]`` in libc++
+===================================================
+
+Libc++ adds ``[[nodiscard]]`` to functions in a lot of places. The standards
+committee has decided to not have a recommended practice where to put them, so
+this document lists where ``[[nodiscard]]`` should be applied in libc++.
+
+When should ``[[nodiscard]]`` be added to functions?
+====================================================
+
+``[[nodiscard]]`` should be applied to functions
+
+- where discarding the return value is most likely a correctness issue.
+  For example a locking constructor in ``unique_lock``.
+
+- where discarding the return value likely points to the user wanting to do
+  something 
diff erent. For example ``vector::empty()``, which probably should
+  have been ``vector::clear()``.
+
+  This can help spotting bugs easily which otherwise may take a very long time
+  to find.
+
+- which return a constant. For example ``numeric_limits::min()``.
+- which only observe a value. For example ``string::size()``.
+
+  Code that discards values from these kinds of functions is dead code. It can
+  either be removed, or the programmer meant to do something 
diff erent.
+
+- where discarding the value is most likely a misuse of the function. For
+  example ``find``.
+
+  This protects programmers from assuming too much about how the internals of
+  a function work, making code more robust in the presence of future
+  optimizations.
+
+What should be done when adding ``[[nodiscard]]`` to a function?
+================================================================
+
+Applications of ``[[nodiscard]]`` are code like any other code, so we aim to
+test them. This can be done with a ``.verify.cpp`` test. Many examples are
+available. Just look for tests with the suffix ``.nodiscard.verify.cpp``.

diff  --git a/libcxx/docs/index.rst b/libcxx/docs/index.rst
index aa1bd4b83b265b..2a7e47dfe6d88b 100644
--- a/libcxx/docs/index.rst
+++ b/libcxx/docs/index.rst
@@ -189,6 +189,7 @@ Design Documents
    DesignDocs/FeatureTestMacros
    DesignDocs/FileTimeType
    DesignDocs/HeaderRemovalPolicy
+   DesignDocs/NodiscardPolicy
    DesignDocs/NoexceptPolicy
    DesignDocs/PSTLIntegration
    DesignDocs/ThreadingSupportAPI