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

[Hristo Hristov via libcxx-commits]

https://github.com/Zingam updated https://github.com/llvm/llvm-project/pull/178384

>From 710e3135a7fc68b439aa5846ecd90a501e7ced1f Mon Sep 17 00:00:00 2001
From: Hristo Hristov <hghristov.rmm at gmail.com>
Date: Wed, 28 Jan 2026 11:22:45 +0200
Subject: [PATCH 1/2] [libc++][docs] Update `[[nodiscard]]` coding guide lines

as suggested in https://github.com/llvm/llvm-project/pull/176936#pullrequestreview-3706775444
---
 libcxx/docs/CodingGuidelines.rst | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/libcxx/docs/CodingGuidelines.rst b/libcxx/docs/CodingGuidelines.rst
index 97e6feef9d79b..8e4ed0084391d 100644
--- a/libcxx/docs/CodingGuidelines.rst
+++ b/libcxx/docs/CodingGuidelines.rst
@@ -165,7 +165,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, such as:
+- 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

>From 25acaf93cc04961fcf0e5ff898a69b296af6058e Mon Sep 17 00:00:00 2001
From: Hristo Hristov <hristo.goshev.hristov at gmail.com>
Date: Tue, 3 Feb 2026 10:25:47 +0200
Subject: [PATCH 2/2] Update libcxx/docs/CodingGuidelines.rst

Co-authored-by: Nikolas Klauser <nikolasklauser at berlin.de>
---
 libcxx/docs/CodingGuidelines.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/libcxx/docs/CodingGuidelines.rst b/libcxx/docs/CodingGuidelines.rst
index 8e4ed0084391d..94827a0067a5c 100644
--- a/libcxx/docs/CodingGuidelines.rst
+++ b/libcxx/docs/CodingGuidelines.rst
@@ -165,7 +165,7 @@ 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 functions if Clang already diagnoses unused results, such as:
+``[[nodiscard]]`` should not be applied to functions if Clang already diagnoses unused results, for example:
 - conversion functions
 - equality operators
 - relational operators