[libcxx-commits] [libcxx] e6c73eb - [libc++][docs] Update `[[nodiscard]]` coding guidelines (#178384)

[via libcxx-commits]

Author: Hristo Hristov
Date: 2026-02-09T18:44:45+02:00
New Revision: e6c73eb0c4c38fa18450c96154228e8ea73799be

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

LOG: [libc++][docs] Update `[[nodiscard]]` coding guidelines (#178384)

as requested in
https://github.com/llvm/llvm-project/pull/176936#pullrequestreview-3706775444

Clarifies when not to apply `[[nodiscard]]`.


https://libcxx.llvm.org/CodingGuidelines.html#apply-nodiscard-where-relevant

---------

Co-authored-by: Nikolas Klauser <nikolasklauser at berlin.de>
Co-authored-by: Hristo Hristov <zingam at outlook.com>

Added: 
    

Modified: 
    libcxx/docs/CodingGuidelines.rst

Removed: 
    


################################################################################
diff  --git a/libcxx/docs/CodingGuidelines.rst b/libcxx/docs/CodingGuidelines.rst
index cb2361c2fc0f2..c1ea6acf58df6 100644
--- a/libcxx/docs/CodingGuidelines.rst
+++ b/libcxx/docs/CodingGuidelines.rst
@@ -175,7 +175,10 @@ have a recommended practice where to put them, so libc++ applies it whenever it
   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.
 
-``[[nodiscard]]`` should not be applied to conversion functions because Clang already diagnoses unused cast results.
+``[[nodiscard]]`` should not be applied to functions if Clang already diagnoses unused results, for example:
+- conversion functions
+- equality operators
+- relational operators
 
 Applications of ``[[nodiscard]]`` are code like any other code, so we aim to test them on public interfaces. This can be
 done with a ``.verify.cpp`` test. Many examples are available. Just look for tests with the suffix