From cea571dad47a8138a37ed5514650ee9a78b2c6ca Mon Sep 17 00:00:00 2001
From: Volker Dusch <volker@tideways-gmbh.com>
Date: Thu, 2 Apr 2026 02:31:53 +0200
Subject: [PATCH 1/3] Translate `nodiscard` Attribute

---
 language/predefined/attributes/nodiscard.xml  | 185 ++++++++++++++++++
 .../attributes/nodiscard/construct.xml        |  54 +++++
 2 files changed, 239 insertions(+)
 create mode 100644 language/predefined/attributes/nodiscard.xml
 create mode 100644 language/predefined/attributes/nodiscard/construct.xml

diff --git a/language/predefined/attributes/nodiscard.xml b/language/predefined/attributes/nodiscard.xml
new file mode 100644
index 000000000..1f4053a52
--- /dev/null
+++ b/language/predefined/attributes/nodiscard.xml
@@ -0,0 +1,185 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- EN-Revision: 30bda33771e1c8fa8fc8a5ee7559fd7fa189caa0 Maintainer: nobody Status: ready -->
+<!-- Reviewed: no -->
+<reference xml:id="class.nodiscard" role="class" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude">
+ <title>Das Attribut NoDiscard</title>
+ <titleabbrev>NoDiscard</titleabbrev>
+
+ <partintro>
+
+  <section xml:id="nodiscard.intro">
+   &reftitle.intro;
+   <simpara>
+    Dieses Attribut kann verwendet werden, um zu kennzeichnen, dass der
+    Rückgabewert einer Funktion oder Methode nicht verworfen werden sollte.
+    Wenn der Rückgabewert in keiner Weise verwendet wird, wird eine Warnung
+    ausgegeben.
+   </simpara>
+   <simpara>
+    Dies ist nützlich bei Funktionen, bei denen das eine fehlende Prüfung des
+    Rückgabewerts wahrscheinlich ein Fehler ist.
+   </simpara>
+   <simpara>
+    Um den Rückgabewert einer solchen Funktion absichtlich zu verwerfen, kann
+    ein (void)-Cast verwendet werden, um die Warnung zu unterdrücken.
+   </simpara>
+   <note>
+    <simpara>
+     Da Attribute auf Abwärtskompatibilität ausgelegt sind, kann
+     <code>#[\NoDiscard]</code> auch dann zu Funktionen und Methoden 
+     hinzugefügt werden, wenn PHP 8.4 oder älter unterstützt werden muss; 
+     es hat dann lediglich keine Wirkung. 
+     Unter PHP 8.5 und neuer wird eine Warnung ausgegeben, wenn das 
+     Ergebnis unbenutzt bleibt. Um die Warnung ohne Verwendung von
+     <code>(void)</code> zu unterdrücken, das vor PHP 8.5
+     nicht unterstützt wird, kann beispielsweise eine Variable wie
+     <code>$_</code> verwendet werden.
+    </simpara>
+   </note>
+  </section>
+
+  <section xml:id="nodiscard.synopsis">
+   &reftitle.classsynopsis;
+
+   <classsynopsis class="class">
+    <ooclass>
+     <modifier role="attribute">#[\Attribute]</modifier>
+     <modifier>final</modifier>
+     <classname>NoDiscard</classname>
+    </ooclass>
+
+    <classsynopsisinfo role="comment">&Properties;</classsynopsisinfo>
+    <fieldsynopsis>
+     <modifier>public</modifier>
+     <modifier>readonly</modifier>
+     <type class="union"><type>string</type><type>null</type></type>
+     <varname linkend="nodiscard.props.message">message</varname>
+    </fieldsynopsis>
+
+    <classsynopsisinfo role="comment">&Methods;</classsynopsisinfo>
+    <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.nodiscard')/db:refentry/db:refsect1[@role='description']/descendant::db:constructorsynopsis[@role='NoDiscard'])">
+     <xi:fallback/>
+    </xi:include>
+   </classsynopsis>
+
+  </section>
+
+  <section xml:id="nodiscard.props">
+   &reftitle.properties;
+   <variablelist>
+    <varlistentry xml:id="nodiscard.props.message">
+     <term><varname>message</varname></term>
+     <listitem>
+      <simpara>
+       Eine optionale Meldung, die erklärt, warum der Rückgabewert nicht
+       verworfen werden sollte.
+      </simpara>
+     </listitem>
+    </varlistentry>
+   </variablelist>
+  </section>
+
+  <section>
+   &reftitle.examples;
+   <example>
+    <title>Grundlegende Verwendung</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+
+/**
+ * Verarbeitet alle angegebenen Elemente und gibt ein Array mit den
+ * Ergebnissen der Operation für jedes Element zurück. `null` bedeutet
+ * Erfolg und eine Exception bedeutet einen Fehler. Die Schlüssel des
+ * Ergebnisarrays entsprechen den Schlüsseln des $items-Arrays.
+ *
+ * @param array<string> $items
+ * @return array<null|Exception>
+ */
+#[\NoDiscard("da die Verarbeitung einzelner Elemente fehlschlagen kann")]
+function bulk_process(array $items): array {
+ $results = [];
+
+ foreach ($items as $key => $item) {
+  if (\random_int(0, 9999) < 9999) {
+   // Simuliere das etwas Sinnvolles mit $item passiert,
+   // was in 99,99 % der Fälle erfolgreich ist.
+   echo "Verarbeite {$item}", PHP_EOL;
+   $error = null;
+  } else {
+   $error = new \Exception("Verarbeitung von {$item} fehlgeschlagen.");
+  }
+
+  $results[$key] = $error;
+ }
+
+ return $results;
+}
+
+bulk_process($items);
+
+?>
+]]>
+    </programlisting>
+    &example.outputs.85.similar;
+    <screen>
+<![CDATA[
+Warning: The return value of function bulk_process() should either be used or intentionally ignored by casting it as (void), da die Verarbeitung einzelner Elemente fehlschlagen kann
+]]>
+    </screen>
+   </example>
+   <example>
+    <title>Rückgabewert absichtlich verwerfen</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+
+#[\NoDiscard]
+function some_command(): int {
+    return 1;
+}
+
+// Warnung mit (void) unterdrücken - PHP 8.5+
+(void) some_command();
+
+// Für Kompatibilität mit PHP-Versionen vor 8.5 eine temporäre Variable verwenden
+$_ = some_command();
+
+?>
+]]>
+    </programlisting>
+   </example>
+  </section>
+
+  <section xml:id="nodiscard.seealso">
+   &reftitle.seealso;
+   <simplelist>
+    <member><link linkend="language.attributes">Übersicht über die Attribute</link></member>
+   </simplelist>
+  </section>
+
+ </partintro>
+
+ &language.predefined.attributes.nodiscard.construct;
+
+</reference>
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+indent-tabs-mode:nil
+sgml-parent-document:nil
+sgml-default-dtd-file:"~/.phpdoc/manual.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+End:
+vim600: syn=xml fen fdm=syntax fdl=2 si
+vim: et tw=78 syn=sgml
+vi: ts=1 sw=1
+-->
diff --git a/language/predefined/attributes/nodiscard/construct.xml b/language/predefined/attributes/nodiscard/construct.xml
new file mode 100644
index 000000000..e8b554330
--- /dev/null
+++ b/language/predefined/attributes/nodiscard/construct.xml
@@ -0,0 +1,54 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- EN-Revision: 02bee41067ab2822cbffcb4b3b2387f79488dffd Maintainer: nobody Status: ready -->
+<!-- Reviewed: no -->
+<refentry xml:id="nodiscard.construct" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
+ <refnamediv>
+  <refname>NoDiscard::__construct</refname>
+  <refpurpose>Erstellt eine neue Instanz des Attributs NoDiscard</refpurpose>
+ </refnamediv>
+
+ <refsect1 role="description">
+  &reftitle.description;
+  <constructorsynopsis role="NoDiscard">
+   <modifier>public</modifier> <methodname>NoDiscard::__construct</methodname>
+   <methodparam choice="opt"><type class="union"><type>string</type><type>null</type></type><parameter>message</parameter><initializer>&null;</initializer></methodparam>
+  </constructorsynopsis>
+  <simpara>
+   Erstellt eine neue Instanz von <classname>NoDiscard</classname>.
+  </simpara>
+ </refsect1>
+
+ <refsect1 role="parameters">
+  &reftitle.parameters;
+  <variablelist>
+   <varlistentry>
+    <term><parameter>message</parameter></term>
+    <listitem>
+     <simpara>
+      Der Wert der Eigenschaft <property linkend="nodiscard.props.message">message</property>.
+     </simpara>
+    </listitem>
+   </varlistentry>
+  </variablelist>
+ </refsect1>
+</refentry>
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+indent-tabs-mode:nil
+sgml-parent-document:nil
+sgml-default-dtd-file:"~/.phpdoc/manual.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+End:
+vim600: syn=xml fen fdm=syntax fdl=2 si
+vim: et tw=78 syn=sgml
+vi: ts=1 sw=1
+-->

From 018e732b6e5a7ae2060182f1dfc5cc40b80c2944 Mon Sep 17 00:00:00 2001
From: Volker Dusch <volker@tideways-gmbh.com>
Date: Thu, 2 Apr 2026 02:43:14 +0200
Subject: [PATCH 2/3] Add nodiscard to attributes.xml

---
 language/predefined/attributes.xml | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/language/predefined/attributes.xml b/language/predefined/attributes.xml
index 5167a43ab..a7ca63817 100644
--- a/language/predefined/attributes.xml
+++ b/language/predefined/attributes.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- EN-Revision: e890e4a7f97a9ea85e60a38443e7c8eb7ae9383f Maintainer: samesch Status: ready -->
+<!-- EN-Revision: 02bee41067ab2822cbffcb4b3b2387f79488dffd Maintainer: samesch Status: ready -->
 <!-- Reviewed: no -->
 <part xml:id="reserved.attributes" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <title>Vordefinierte Attribute</title>
@@ -13,6 +13,7 @@
  &language.predefined.attributes.attribute;
  &language.predefined.attributes.allowdynamicproperties;
  &language.predefined.attributes.deprecated;
+ &language.predefined.attributes.nodiscard;
  &language.predefined.attributes.override;
  &language.predefined.attributes.returntypewillchange;
  &language.predefined.attributes.sensitiveparameter;

From 4852feb06081037e34522019fd680e8c88087bb3 Mon Sep 17 00:00:00 2001
From: Volker Dusch <247397+edorian@users.noreply.github.com>
Date: Thu, 2 Apr 2026 18:18:16 +0200
Subject: [PATCH 3/3] Fix typo
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Tim Düsterhus <timwolla@googlemail.com>
---
 language/predefined/attributes/nodiscard.xml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/language/predefined/attributes/nodiscard.xml b/language/predefined/attributes/nodiscard.xml
index 1f4053a52..d8aca5faf 100644
--- a/language/predefined/attributes/nodiscard.xml
+++ b/language/predefined/attributes/nodiscard.xml
@@ -16,7 +16,7 @@
     ausgegeben.
    </simpara>
    <simpara>
-    Dies ist nützlich bei Funktionen, bei denen das eine fehlende Prüfung des
+    Dies ist nützlich bei Funktionen, bei denen die fehlende Prüfung des
     Rückgabewerts wahrscheinlich ein Fehler ist.
    </simpara>
    <simpara>