Skip to content

Commit 33a0e91

Browse files
KentarouTakedaKentarouTakeda
authored
日本語訳の存在しない新規翻訳ページ（NoDiscard, StreamBucket） (#338)
* 日本語訳の存在しない新規翻訳ページ（NoDiscard, StreamBucket） * StreamBucket: simparapara → simpara の上流修正に追従 php/doc-en@a7be7e9abb (#5395) の修正を反映。 * NoDiscard: 訳語改善とコード例コメントの日本語化 - 「破棄する」→「無視する」に変更（レビュー指摘対応） - コード例内の英語コメントを日本語に翻訳
1 parent a6e6239 commit 33a0e91

4 files changed

Lines changed: 353 additions & 1 deletion

File tree

‎language/predefined/attributes.xml‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
<?xml version="1.0" encoding="utf-8"?>
22
<!-- $Revision$ -->
3-
<!-- EN-Revision: e890e4a7f97a9ea85e60a38443e7c8eb7ae9383f Maintainer: mumumu Status: ready -->
3+
<!-- EN-Revision: 02bee41067ab2822cbffcb4b3b2387f79488dffd Maintainer: mumumu Status: ready -->
44
<part xml:id="reserved.attributes" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
55
<title>定義済みのアトリビュート</title>
66

@@ -13,6 +13,7 @@
1313
&language.predefined.attributes.attribute;
1414
&language.predefined.attributes.allowdynamicproperties;
1515
&language.predefined.attributes.deprecated;
16+
&language.predefined.attributes.nodiscard;
1617
&language.predefined.attributes.override;
1718
&language.predefined.attributes.returntypewillchange;
1819
&language.predefined.attributes.sensitiveparameter;

‎language/predefined/attributes/nodiscard.xml‎

Lines changed: 175 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,175 @@
1+
<?xml version="1.0" encoding="utf-8"?>
2+
<!-- $Revision$ -->
3+
<!-- EN-Revision: 02bee41067ab2822cbffcb4b3b2387f79488dffd Maintainer: KentarouTakeda Status: ready -->
4+
<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">
5+
<title>NoDiscard アトリビュート</title>
6+
<titleabbrev>NoDiscard</titleabbrev>
7+
8+
<partintro>
9+
10+
<section xml:id="nodiscard.intro">
11+
&reftitle.intro;
12+
<simpara>
13+
このアトリビュートは、関数やメソッドの戻り値を無視すべきでないことを示すために使います。
14+
戻り値がまったく使われなかった場合、警告が発生します。
15+
</simpara>
16+
<simpara>
17+
これは、戻り値を確認しないことがバグにつながる可能性が高い関数に役立ちます。
18+
</simpara>
19+
<simpara>
20+
このような関数の戻り値を意図的に無視するには、(void) キャストを使って警告を抑制します。
21+
</simpara>
22+
<note>
23+
<simpara>
24+
アトリビュートは後方互換性を持つように設計されているため、
25+
PHP 8.4 以前をサポートする場合でも
26+
<code>#[\NoDiscard]</code> を関数やメソッドに追加できます。単に何も起こらないだけです。
27+
PHP 8.5 以降では、戻り値が使われなかった場合に警告が発生します。
28+
PHP 8.5 より前ではサポートされていない <code>(void)</code> を使わずに
29+
警告を抑制するには、<code>$_</code> のような変数を使うことを検討してください。
30+
</simpara>
31+
</note>
32+
</section>
33+
34+
<section xml:id="nodiscard.synopsis">
35+
&reftitle.classsynopsis;
36+
37+
<classsynopsis class="class">
38+
<ooclass>
39+
<modifier>final</modifier>
40+
<classname>NoDiscard</classname>
41+
</ooclass>
42+
43+
<classsynopsisinfo role="comment">&Properties;</classsynopsisinfo>
44+
<fieldsynopsis>
45+
<modifier>public</modifier>
46+
<modifier>readonly</modifier>
47+
<type class="union"><type>string</type><type>null</type></type>
48+
<varname linkend="nodiscard.props.message">message</varname>
49+
</fieldsynopsis>
50+
51+
<classsynopsisinfo role="comment">&Methods;</classsynopsisinfo>
52+
<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'])">
53+
<xi:fallback/>
54+
</xi:include>
55+
</classsynopsis>
56+
57+
</section>
58+
59+
<section xml:id="nodiscard.props">
60+
&reftitle.properties;
61+
<variablelist>
62+
<varlistentry xml:id="nodiscard.props.message">
63+
<term><varname>message</varname></term>
64+
<listitem>
65+
<simpara>
66+
戻り値を無視すべきでない理由を説明する、任意のメッセージ。
67+
</simpara>
68+
</listitem>
69+
</varlistentry>
70+
</variablelist>
71+
</section>
72+
73+
<section>
74+
&reftitle.examples;
75+
<example>
76+
<title>基本的な使い方</title>
77+
<programlisting role="php">
78+
<![CDATA[
79+
<?php
80+
81+
/**
82+
* 与えられた全てのアイテムを処理し、各アイテムの処理結果を
83+
* 配列で返す。`null` は成功を、Exception はエラーを示す。
84+
* 結果の配列のキーは $items 配列のキーと一致する。
85+
*
86+
* @param array<string> $items
87+
* @return array<null|Exception>
88+
*/
89+
#[\NoDiscard("as processing might fail for individual items")]
90+
function bulk_process(array $items): array {
91+
$results = [];
92+
93+
foreach ($items as $key => $item) {
94+
if (\random_int(0, 9999) < 9999) {
95+
// $item に対して何か有用な処理を行う想定。
96+
// 99.99% のケースで成功する。
97+
echo "Processing {$item}", PHP_EOL;
98+
$error = null;
99+
} else {
100+
$error = new \Exception("Failed to process {$item}.");
101+
}
102+
103+
$results[$key] = $error;
104+
}
105+
106+
return $results;
107+
}
108+
109+
bulk_process($items);
110+
111+
?>
112+
]]>
113+
</programlisting>
114+
&example.outputs.85.similar;
115+
<screen>
116+
<![CDATA[
117+
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
118+
]]>
119+
</screen>
120+
</example>
121+
<example>
122+
<title>戻り値を意図的に無視する</title>
123+
<programlisting role="php">
124+
<![CDATA[
125+
<?php
126+
127+
#[\NoDiscard]
128+
function some_command(): int {
129+
return 1;
130+
}
131+
132+
// (void) を使って警告を抑制する - PHP 8.5 以降
133+
(void) some_command();
134+
135+
// PHP 8.5 より前のバージョンとの互換性のため、一時変数を使う
136+
$_ = some_command();
137+
138+
?>
139+
]]>
140+
</programlisting>
141+
</example>
142+
</section>
143+
144+
<section xml:id="nodiscard.seealso">
145+
&reftitle.seealso;
146+
<simplelist>
147+
<member><link linkend="language.attributes">アトリビュートの概要</link></member>
148+
</simplelist>
149+
</section>
150+
151+
</partintro>
152+
153+
&language.predefined.attributes.nodiscard.construct;
154+
155+
</reference>
156+
<!-- Keep this comment at the end of the file
157+
Local variables:
158+
mode: sgml
159+
sgml-omittag:t
160+
sgml-shorttag:t
161+
sgml-minimize-attributes:nil
162+
sgml-always-quote-attributes:t
163+
sgml-indent-step:1
164+
sgml-indent-data:t
165+
indent-tabs-mode:nil
166+
sgml-parent-document:nil
167+
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
168+
sgml-exposed-tags:nil
169+
sgml-local-catalogs:nil
170+
sgml-local-ecat-files:nil
171+
End:
172+
vim600: syn=xml fen fdm=syntax fdl=2 si
173+
vim: et tw=78 syn=sgml
174+
vi: ts=1 sw=1
175+
-->

‎language/predefined/attributes/nodiscard/construct.xml‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
<?xml version="1.0" encoding="utf-8"?>
2+
<!-- $Revision$ -->
3+
<!-- EN-Revision: 02bee41067ab2822cbffcb4b3b2387f79488dffd Maintainer: KentarouTakeda Status: ready -->
4+
<refentry xml:id="nodiscard.construct" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
5+
<refnamediv>
6+
<refname>NoDiscard::__construct</refname>
7+
<refpurpose>新しい NoDiscard のインスタンスを作成する</refpurpose>
8+
</refnamediv>
9+
10+
<refsect1 role="description">
11+
&reftitle.description;
12+
<constructorsynopsis role="NoDiscard">
13+
<modifier>public</modifier> <methodname>NoDiscard::__construct</methodname>
14+
<methodparam choice="opt"><type class="union"><type>string</type><type>null</type></type><parameter>message</parameter><initializer>&null;</initializer></methodparam>
15+
</constructorsynopsis>
16+
<simpara>
17+
新しい <classname>NoDiscard</classname> のインスタンスを作成します。
18+
</simpara>
19+
</refsect1>
20+
21+
<refsect1 role="parameters">
22+
&reftitle.parameters;
23+
<variablelist>
24+
<varlistentry>
25+
<term><parameter>message</parameter></term>
26+
<listitem>
27+
<simpara>
28+
<property linkend="nodiscard.props.message">message</property> プロパティの値。
29+
</simpara>
30+
</listitem>
31+
</varlistentry>
32+
</variablelist>
33+
</refsect1>
34+
</refentry>
35+
<!-- Keep this comment at the end of the file
36+
Local variables:
37+
mode: sgml
38+
sgml-omittag:t
39+
sgml-shorttag:t
40+
sgml-minimize-attributes:nil
41+
sgml-always-quote-attributes:t
42+
sgml-indent-step:1
43+
sgml-indent-data:t
44+
indent-tabs-mode:nil
45+
sgml-parent-document:nil
46+
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
47+
sgml-exposed-tags:nil
48+
sgml-local-catalogs:nil
49+
sgml-local-ecat-files:nil
50+
End:
51+
vim600: syn=xml fen fdm=syntax fdl=2 si
52+
vim: et tw=78 syn=sgml
53+
vi: ts=1 sw=1
54+
-->

‎reference/stream/streambucket.xml‎

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
<?xml version="1.0" encoding="utf-8"?>
2+
<!-- $Revision$ -->
3+
<!-- EN-Revision: a7be7e9abb82bfd0c69ea341d74fb9456e93f6f6 Maintainer: KentarouTakeda Status: ready -->
4+
<reference xml:id="class.streambucket" role="class" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude">
5+
6+
<title>StreamBucket クラス</title>
7+
<titleabbrev>StreamBucket</titleabbrev>
8+
9+
<partintro>
10+
11+
<section xml:id="streambucket.intro">
12+
&reftitle.intro;
13+
<simpara>
14+
ストリームバケットは、バケット群から取り出すことのできるストリームのチャンクです。
15+
</simpara>
16+
</section>
17+
18+
<section xml:id="streambucket.synopsis">
19+
&reftitle.classsynopsis;
20+
21+
<classsynopsis class="class">
22+
<ooclass>
23+
<modifier>final</modifier>
24+
<classname>StreamBucket</classname>
25+
</ooclass>
26+
27+
<classsynopsisinfo role="comment">&Properties;</classsynopsisinfo>
28+
<fieldsynopsis>
29+
<modifier>public</modifier>
30+
<modifier>readonly</modifier>
31+
<type>resource</type>
32+
<varname linkend="streambucket.props.bucket">bucket</varname>
33+
</fieldsynopsis>
34+
<fieldsynopsis>
35+
<modifier>public</modifier>
36+
<modifier>readonly</modifier>
37+
<type>string</type>
38+
<varname linkend="streambucket.props.data">data</varname>
39+
</fieldsynopsis>
40+
<fieldsynopsis>
41+
<modifier>public</modifier>
42+
<modifier>readonly</modifier>
43+
<type>int</type>
44+
<varname linkend="streambucket.props.datalen">datalen</varname>
45+
</fieldsynopsis>
46+
<fieldsynopsis>
47+
<modifier>public</modifier>
48+
<modifier>readonly</modifier>
49+
<type>int</type>
50+
<varname linkend="streambucket.props.datalength">dataLength</varname>
51+
</fieldsynopsis>
52+
</classsynopsis>
53+
</section>
54+
55+
<section xml:id="streambucket.props">
56+
&reftitle.properties;
57+
<variablelist>
58+
<varlistentry xml:id="streambucket.props.bucket">
59+
<term>resource <varname>bucket</varname></term>
60+
<listitem>
61+
<simpara><literal>userfilter.bucket</literal> リソース。</simpara>
62+
</listitem>
63+
</varlistentry>
64+
<varlistentry xml:id="streambucket.props.data">
65+
<term>string <varname>data</varname></term>
66+
<listitem>
67+
<simpara>バケット内の現在の文字列。</simpara>
68+
</listitem>
69+
</varlistentry>
70+
<varlistentry xml:id="streambucket.props.datalen">
71+
<term>int <varname>datalen</varname></term>
72+
<listitem>
73+
<simpara>
74+
バケット内の文字列の長さ。
75+
PHP 8.4 以降は非推奨であり、<literal>StreamBucket::$dataLength</literal> を使用してください。
76+
</simpara>
77+
</listitem>
78+
</varlistentry>
79+
<varlistentry xml:id="streambucket.props.dataLength">
80+
<term>int <varname>dataLength</varname></term>
81+
<listitem>
82+
<simpara>バケット内の文字列の長さ。</simpara>
83+
</listitem>
84+
</varlistentry>
85+
</variablelist>
86+
</section>
87+
88+
<section role="seealso">
89+
&reftitle.seealso;
90+
<simplelist>
91+
<member><function>stream_bucket_new</function></member>
92+
<member><function>stream_bucket_append</function></member>
93+
<member><function>stream_bucket_prepend</function></member>
94+
<member><function>stream_bucket_make_writeable</function></member>
95+
</simplelist>
96+
</section>
97+
98+
</partintro>
99+
100+
&reference.stream.entities.streambucket;
101+
102+
</reference>
103+
<!-- Keep this comment at the end of the file
104+
Local variables:
105+
mode: sgml
106+
sgml-omittag:t
107+
sgml-shorttag:t
108+
sgml-minimize-attributes:nil
109+
sgml-always-quote-attributes:t
110+
sgml-indent-step:1
111+
sgml-indent-data:t
112+
indent-tabs-mode:nil
113+
sgml-parent-document:nil
114+
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
115+
sgml-exposed-tags:nil
116+
sgml-local-catalogs:nil
117+
sgml-local-ecat-files:nil
118+
End:
119+
vim600: syn=xml fen fdm=syntax fdl=2 si
120+
vim: et tw=78 syn=sgml
121+
vi: ts=1 sw=1
122+
-->

0 commit comments

Comments
 (0)