[DOC-CVS] [doc-en] master: Document #[\NoDiscard] behavior on interface, abstract, and overriding methods (#5618)

Author: Osama Aldemeery (aldemeery)
Committer: GitHub (web-flow)
Pusher: TimWolla
Date: 2026-06-18T21:11:35+02:00

Commit: https://github.com/php/doc-en/commit/e7f89579e2abcecad5a62dd96f11a4926df62e13
Raw diff: https://github.com/php/doc-en/commit/e7f89579e2abcecad5a62dd96f11a4926df62e13.diff

Document #[\NoDiscard] behavior on interface, abstract, and overriding methods (#5618)

Co-authored-by: Louis-Arnaud <[email protected]>

Changed paths:
  M  language/predefined/attributes/nodiscard.xml


Diff:

diff --git a/language/predefined/attributes/nodiscard.xml b/language/predefined/attributes/nodiscard.xml
index baf6c7b82822..b037abe078e7 100644
--- a/language/predefined/attributes/nodiscard.xml
+++ b/language/predefined/attributes/nodiscard.xml
@@ -31,6 +31,20 @@
      consider using a variable like <code>$_</code>.
     </simpara>
    </note>
+   <note>
+    <simpara>
+     <code>#[\NoDiscard]</code> applies to the specific function or method
+     declaration it is written on, and the warning is emitted based on the
+     declaration that is actually called. As a result, adding
+     <code>#[\NoDiscard]</code> to an interface method or an abstract method
+     does not emit a warning, because the method that is invoked is the
+     implementing or overriding method. Likewise, a method that overrides a
+     <code>#[\NoDiscard]</code> method does not emit the warning unless it is
+     itself marked with the attribute. In contrast, a method imported from a
+     trait keeps the attribute, because the trait method is copied into the
+     using class as if declared there.
+    </simpara>
+   </note>
   </section>
 
   <section xml:id="nodiscard.synopsis">