Add NoDiscard attribute translation

language/predefined/attributes/nodiscard.xml

@@ -0,0 +1,179 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision$ -->
+<!-- EN-Revision: 02bee41067ab2822cbffcb4b3b2387f79488dffd Maintainer: lacatoire Status: ready -->
+<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>NoDiscard アトリビュート</title>
+ <titleabbrev>NoDiscard</titleabbrev>
+
+ <partintro>
+
+  <section xml:id="nodiscard.intro">
+   &reftitle.intro;
+   <simpara>
+    このアトリビュートは、関数やメソッドの戻り値を
+    破棄してはいけないことを示すために使用します。
+    戻り値が何にも使われていない場合、警告が発生します。
+   </simpara>
+   <simpara>
+    戻り値を確認しないことがバグにつながる可能性のある関数に対して有用です。
+   </simpara>
+   <simpara>
+    このような関数の戻り値を意図的に破棄するには、
+    (void) キャストを使用して警告を抑制します。
+   </simpara>
+   <note>
+    <simpara>
+     アトリビュートは後方互換性を持つように設計されているため、
+     PHP 8.4 以下をサポートする場合でも
+     <code>#[\NoDiscard]</code> を関数やメソッドに追加できますが、
+     何も起こりません。
+     PHP 8.5 以降では、結果が使用されていない場合に警告が発生します。
+     PHP 8.5 より前ではサポートされていない <code>(void)</code> を使わずに
+     警告を抑制するには、
+     <code>$_</code> のような変数を使用することを検討してください。
+    </simpara>
+   </note>
+  </section>
+
+  <section xml:id="nodiscard.synopsis">
+   &reftitle.classsynopsis;
+
+   <classsynopsis class="class">
+    <ooclass>
+     <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>
+       戻り値を破棄してはいけない理由を説明する任意のメッセージ。
+      </simpara>
+     </listitem>
+    </varlistentry>
+   </variablelist>
+  </section>
+
+  <section>
+   &reftitle.examples;
+   <example>
+    <title>基本的な使い方</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+
+/**
+ * 指定されたすべてのアイテムを処理し、各アイテムの操作結果を
+ * 含む配列を返します。`null` は成功を示し、Exception はエラーを
+ * 示します。結果の配列のキーは $items 配列のキーと一致します。
+ *
+ * @param array<string> $items
+ * @return array<null|Exception>
+ */
+#[\NoDiscard("as processing might fail for individual items")]
+function bulk_process(array $items): array {
+	$results = [];
+
+	foreach ($items as $key => $item) {
+		if (\random_int(0, 9999) < 9999) {
+			// $item に対して有用な処理を行うふりをする。
+			// 99.99% のケースで成功する。
+			echo "Processing {$item}", PHP_EOL;
+			$error = null;
+		} else {
+			$error = new \Exception("Failed to process {$item}.");
+		}
+
+		$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), as processing might fail for individual items
+]]>
+    </screen>
+   </example>
+   <example>
+    <title>戻り値を意図的に破棄する</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+
+#[\NoDiscard]
+function some_command(): int {
+    return 1;
+}
+
+// (void) を使って警告を抑制する - PHP 8.5+
+(void) some_command();
+
+// PHP 8.5 より前のバージョンとの互換性のため、一時変数を使用する
+$_ = some_command();
+
+?>
+]]>
+    </programlisting>
+   </example>
+  </section>
+
+  <section xml:id="nodiscard.seealso">
+   &reftitle.seealso;
+   <simplelist>
+    <member><link linkend="language.attributes">アトリビュート</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
+-->

language/predefined/attributes/nodiscard/construct.xml

@@ -0,0 +1,54 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision$ -->
+<!-- EN-Revision: 02bee41067ab2822cbffcb4b3b2387f79488dffd Maintainer: lacatoire Status: ready -->
+<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>新しい 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>
+   新しい <classname>NoDiscard</classname> のインスタンスを作成します。
+  </simpara>
+ </refsect1>
+
+ <refsect1 role="parameters">
+  &reftitle.parameters;
+  <variablelist>
+   <varlistentry>
+    <term><parameter>message</parameter></term>
+    <listitem>
+     <simpara>
+      <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
+-->