Skip to content

Commit b7c9d20

Browse files
leonardolaraleonardolara
committed
sync with en rev
1 parent cea7c53 commit b7c9d20

3 files changed

Lines changed: 232 additions & 1 deletion

File tree

‎language/predefined/attributes.xml‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
<?xml version="1.0" encoding="utf-8"?> <!-- EN-Revision: e890e4a7f97a9ea85e60a38443e7c8eb7ae9383f Maintainer: leonardolara Status: ready --><!-- CREDITS: adaiasmagdiel,leonardolara -->
1+
<?xml version="1.0" encoding="utf-8"?> <!-- EN-Revision: 02bee41067ab2822cbffcb4b3b2387f79488dffd Maintainer: leonardolara Status: ready --><!-- CREDITS: adaiasmagdiel,leonardolara -->
22
<part xml:id="reserved.attributes" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
33
<title>Atributos Predefinidos</title>
44

@@ -11,6 +11,7 @@
1111
&language.predefined.attributes.attribute;
1212
&language.predefined.attributes.allowdynamicproperties;
1313
&language.predefined.attributes.deprecated;
14+
&language.predefined.attributes.nodiscard;
1415
&language.predefined.attributes.override;
1516
&language.predefined.attributes.returntypewillchange;
1617
&language.predefined.attributes.sensitiveparameter;

‎language/predefined/attributes/nodiscard.xml‎

Lines changed: 177 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,177 @@
1+
<?xml version="1.0" encoding="utf-8"?><!-- EN-Revision: 02bee41067ab2822cbffcb4b3b2387f79488dffd Maintainer: leonardolara Status: ready --><!-- CREDITS: leonardolara -->
2+
<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">
3+
<title>O atributo NoDiscard</title>
4+
<titleabbrev>NoDiscard</titleabbrev>
5+
6+
<partintro>
7+
8+
<section xml:id="nodiscard.intro">
9+
&reftitle.intro;
10+
<simpara>
11+
Este atributo pode ser usado para indicar que o valor de retorno de uma função
12+
ou método não deve ser descartado. Se o valor de retorno não for usado de
13+
nenhuma forma, um aviso será emitido.
14+
</simpara>
15+
<simpara>
16+
Isso é útil para funções onde não verificar o valor de retorno provavelmente
17+
é um bug.
18+
</simpara>
19+
<simpara>
20+
Para descartar intencionalmente o valor de retorno de tal função, use a conversão
21+
(void) para suprimir o aviso.
22+
</simpara>
23+
<note>
24+
<simpara>
25+
Como os atributos são projetados para serem retrocompatíveis,
26+
<code>#[\NoDiscard]</code> pode ser adicionado a funções e métodos
27+
mesmo quando o PHP 8.4 ou versões anteriores são suportados, ele simplesmente não fará nada.
28+
No PHP 8.5 e versões posteriores, um aviso será emitido se o resultado não for usado.
29+
Para suprimir o aviso sem usar <code>(void)</code>,
30+
que não é suportado antes do PHP 8.5,
31+
considere usar uma variável como <code>$_</code>.
32+
</simpara>
33+
</note>
34+
</section>
35+
36+
<section xml:id="nodiscard.synopsis">
37+
&reftitle.classsynopsis;
38+
39+
<classsynopsis class="class">
40+
<ooclass>
41+
<modifier>final</modifier>
42+
<classname>NoDiscard</classname>
43+
</ooclass>
44+
45+
<classsynopsisinfo role="comment">&Properties;</classsynopsisinfo>
46+
<fieldsynopsis>
47+
<modifier>public</modifier>
48+
<modifier>readonly</modifier>
49+
<type class="union"><type>string</type><type>null</type></type>
50+
<varname linkend="nodiscard.props.message">message</varname>
51+
</fieldsynopsis>
52+
53+
<classsynopsisinfo role="comment">&Methods;</classsynopsisinfo>
54+
<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'])">
55+
<xi:fallback/>
56+
</xi:include>
57+
</classsynopsis>
58+
59+
</section>
60+
61+
<section xml:id="nodiscard.props">
62+
&reftitle.properties;
63+
<variablelist>
64+
<varlistentry xml:id="nodiscard.props.message">
65+
<term><varname>message</varname></term>
66+
<listitem>
67+
<simpara>
68+
Uma mensagem opcional explicando por que o valor retornado não deve ser descartado.
69+
</simpara>
70+
</listitem>
71+
</varlistentry>
72+
</variablelist>
73+
</section>
74+
75+
<section>
76+
&reftitle.examples;
77+
<example>
78+
<title>Uso básico</title>
79+
<programlisting role="php">
80+
<![CDATA[
81+
<?php
82+
83+
/**
84+
* Processa todos os itens fornecidos e retorna um array com os resultados da
85+
* operação para cada item. `null` indica sucesso e uma exceção indica
86+
* um erro. As chaves do array de resultados correspondem às chaves do array $items.
87+
*
88+
* @param array<string> $items
89+
* @return array<null|Exception>
90+
*/
91+
#[\NoDiscard("pois o processamento pode falhar para itens individuais")]
92+
function bulk_process(array $items): array {
93+
$results = [];
94+
95+
foreach ($items as $key => $item) {
96+
if (\random_int(0, 9999) < 9999) {
97+
// Finge fazer algo útil com $item,
98+
// o que terá sucesso em 99,99% dos casos.
99+
echo "Processando {$item}", PHP_EOL;
100+
$error = null;
101+
} else {
102+
$error = new \Exception("Falha ao processar {$item}.");
103+
}
104+
105+
$results[$key] = $error;
106+
}
107+
108+
return $results;
109+
}
110+
111+
bulk_process($items);
112+
113+
?>
114+
]]>
115+
</programlisting>
116+
&example.outputs.85.similar;
117+
<screen>
118+
<![CDATA[
119+
Warning: The return value of function bulk_process() should either be used or intentionally ignored by casting it as (void), pois o processamento pode falhar para itens individuais
120+
]]>
121+
</screen>
122+
</example>
123+
<example>
124+
<title>Descartar intencionalmente o valor de retorno</title>
125+
<programlisting role="php">
126+
<![CDATA[
127+
<?php
128+
129+
#[\NoDiscard]
130+
function some_command(): int {
131+
return 1;
132+
}
133+
134+
// Suprimir o aviso usando (void) - PHP 8.5+
135+
(void) some_command();
136+
137+
// Para compatibilidade com versões do PHP anteriores à 8.5, utilize uma variável temporária
138+
$_ = some_command();
139+
140+
?>
141+
]]>
142+
</programlisting>
143+
</example>
144+
</section>
145+
146+
<section xml:id="nodiscard.seealso">
147+
&reftitle.seealso;
148+
<simplelist>
149+
<member><link linkend="language.attributes">Visão geral dos atributos</link></member>
150+
</simplelist>
151+
</section>
152+
153+
</partintro>
154+
155+
&language.predefined.attributes.nodiscard.construct;
156+
157+
</reference>
158+
<!-- Keep this comment at the end of the file
159+
Local variables:
160+
mode: sgml
161+
sgml-omittag:t
162+
sgml-shorttag:t
163+
sgml-minimize-attributes:nil
164+
sgml-always-quote-attributes:t
165+
sgml-indent-step:1
166+
sgml-indent-data:t
167+
indent-tabs-mode:nil
168+
sgml-parent-document:nil
169+
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
170+
sgml-exposed-tags:nil
171+
sgml-local-catalogs:nil
172+
sgml-local-ecat-files:nil
173+
End:
174+
vim600: syn=xml fen fdm=syntax fdl=2 si
175+
vim: et tw=78 syn=sgml
176+
vi: ts=1 sw=1
177+
-->

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

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

0 commit comments

Comments
 (0)