Skip to content

Add translations for the nodiscard Attribute #220

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
edorian wants to merge 3 commits into
base: master
Choose a base branch
from
+241 −1
Open

Add translations for the nodiscard Attribute #220

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
cea571d
Translate `nodiscard` Attribute
edorian Apr 2, 2026
018e732
Add nodiscard to attributes.xml
edorian Apr 2, 2026
4852feb
Fix typo
edorian Apr 2, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion language/predefined/attributes.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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>
Expand All @@ -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;
Expand Down
185 changes: 185 additions & 0 deletions language/predefined/attributes/nodiscard.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 die 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
-->
54 changes: 54 additions & 0 deletions language/predefined/attributes/nodiscard/construct.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
-->
Loading