Skip to content

Commit f050d59

Browse files
mmalferovmmalferov
authored
Create NoDiscard (#1153)
* Create construct.xml * Create nodiscard.xml
1 parent aea2349 commit f050d59

File tree

2 files changed

+232
-0
lines changed

2 files changed

+232
-0
lines changed

‎language/predefined/attributes/nodiscard.xml‎

Lines changed: 178 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,178 @@
1+
<?xml version="1.0" encoding="utf-8"?>
2+
<!-- EN-Revision: 02bee41067ab2822cbffcb4b3b2387f79488dffd Maintainer: malferov Status: ready -->
3+
<!-- Reviewed: no -->
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+
не обработали: не передали, не вернули, не присвоили переменной и не указали в выражении.
16+
</simpara>
17+
<simpara>
18+
Атрибут полезно нацеливать на функции, результат которых нельзя игнорировать из-за риска
19+
пропустить ошибку.
20+
</simpara>
21+
<simpara>
22+
Предупреждение подавляют инструкцией (void), когда требуется преднамеренно проигнорировать
23+
обработку результата функции, на которую нацелили атрибут.
24+
</simpara>
25+
<note>
26+
<simpara>
27+
В PHP 8.4 или ниже движок проигнорирует атрибут <code>#[\NoDiscard]</code>,
28+
который добавили к функции или методу,
29+
поскольку атрибуты разработали с учётом обратной совместимости.
30+
В PHP 8.5 и выше движок выдаст предупреждение, если результат проигнорировали.
31+
Присваивание результата переменной наподобие <code>$_</code>
32+
не нарушит работу кода на прежних версиях PHP,
33+
в которых ещё не добавили поддержку инструкции <code>(void)</code>,
34+
и подавит предупреждение при переносе кода на PHP 8.5.
35+
</simpara>
36+
</note>
37+
</section>
38+
39+
<section xml:id="nodiscard.synopsis">
40+
&reftitle.classsynopsis;
41+
42+
<classsynopsis class="class">
43+
<ooclass>
44+
<modifier>final</modifier>
45+
<classname>NoDiscard</classname>
46+
</ooclass>
47+
48+
<classsynopsisinfo role="comment">&Properties;</classsynopsisinfo>
49+
<fieldsynopsis>
50+
<modifier>public</modifier>
51+
<modifier>readonly</modifier>
52+
<type class="union"><type>string</type><type>null</type></type>
53+
<varname linkend="nodiscard.props.message">message</varname>
54+
</fieldsynopsis>
55+
56+
<classsynopsisinfo role="comment">&Methods;</classsynopsisinfo>
57+
<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'])">
58+
<xi:fallback/>
59+
</xi:include>
60+
</classsynopsis>
61+
62+
</section>
63+
64+
<section xml:id="nodiscard.props">
65+
&reftitle.properties;
66+
<variablelist>
67+
<varlistentry xml:id="nodiscard.props.message">
68+
<term><varname>message</varname></term>
69+
<listitem>
70+
<simpara>
71+
Необязательное сообщение, которое объясняет, почему нельзя игнорировать значение возврата.
72+
</simpara>
73+
</listitem>
74+
</varlistentry>
75+
</variablelist>
76+
</section>
77+
78+
<section>
79+
&reftitle.examples;
80+
<example>
81+
<title>Базовый пример</title>
82+
<programlisting role="php">
83+
<![CDATA[
84+
<?php
85+
86+
/**
87+
* Метод возвращает массив, элементы которого содержат результат обработки
88+
* каждого отдельного значения. Значение null указывает, что обработка элемента завершилась без ошибок,
89+
* а объект Exception указывает на ошибку. Ключи в массиве с результатами обработки совпадают с ключами массива $items.
90+
*
91+
* @param array<string> $items
92+
* @return array<null|Exception>
93+
*/
94+
#[\NoDiscard("поскольку вероятна ошибка при обработке отдельного элемента")]
95+
function bulk_process(array $items): array
96+
{
97+
$results = [];
98+
99+
foreach ($items as $key => $item) {
100+
if (\random_int(0, 9999) < 9999) {
101+
// Имитация полезной операции со значением $item
102+
// с вероятностью успеха 99,99 %.
103+
echo "Обработка значения {$item}", PHP_EOL;
104+
$error = null;
105+
} else {
106+
$error = new \Exception("Ошибка обработки значения {$item}.");
107+
}
108+
109+
$results[$key] = $error;
110+
}
111+
112+
return $results;
113+
}
114+
115+
bulk_process($items);
116+
]]>
117+
</programlisting>
118+
&example.outputs.85.similar;
119+
<screen>
120+
<![CDATA[
121+
Warning: The return value of function bulk_process() should either be used or intentionally ignored by casting it as (void), поскольку вероятна ошибка при обработке отдельного элемента
122+
]]>
123+
</screen>
124+
</example>
125+
<example>
126+
<title>Преднамеренное игнорирование значения возврата</title>
127+
<programlisting role="php">
128+
<![CDATA[
129+
<?php
130+
131+
#[\NoDiscard]
132+
function some_command(): int
133+
{
134+
return 1;
135+
}
136+
137+
// Подавление предупреждения инструкцией (void) — поддерживается в PHP 8.5+
138+
(void) some_command();
139+
140+
// Временная переменная сохранит обратную совместимость с PHP до версии 8.5
141+
$_ = some_command();
142+
]]>
143+
</programlisting>
144+
</example>
145+
</section>
146+
147+
<section xml:id="nodiscard.seealso">
148+
&reftitle.seealso;
149+
<simplelist>
150+
<member><link linkend="language.attributes">Введение в атрибуты</link></member>
151+
</simplelist>
152+
</section>
153+
154+
</partintro>
155+
156+
&language.predefined.attributes.nodiscard.construct;
157+
158+
</reference>
159+
<!-- Keep this comment at the end of the file
160+
Local variables:
161+
mode: sgml
162+
sgml-omittag:t
163+
sgml-shorttag:t
164+
sgml-minimize-attributes:nil
165+
sgml-always-quote-attributes:t
166+
sgml-indent-step:1
167+
sgml-indent-data:t
168+
indent-tabs-mode:nil
169+
sgml-parent-document:nil
170+
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
171+
sgml-exposed-tags:nil
172+
sgml-local-catalogs:nil
173+
sgml-local-ecat-files:nil
174+
End:
175+
vim600: syn=xml fen fdm=syntax fdl=2 si
176+
vim: et tw=78 syn=sgml
177+
vi: ts=1 sw=1
178+
-->

‎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+
<!-- EN-Revision: 02bee41067ab2822cbffcb4b3b2387f79488dffd Maintainer: malferov Status: ready -->
3+
<!-- Reviewed: no -->
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+
-->

0 commit comments

Comments
 (0)