Skip to content

[Sync ES] Update XML documentation for MongoDB methods to improve clarity and consistency #599

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

Merged
PhilDaiguille merged 1 commit into from
May 10, 2026
Merged

[Sync ES] Update XML documentation for MongoDB methods to improve clarity and consistency #599

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
332 changes: 174 additions & 158 deletions language/types/type-juggling.xml
View file
Open in desktop

Large diffs are not rendered by default.

50 changes: 41 additions & 9 deletions language/types/void.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,24 +1,56 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 161dde4fe721309398dd324edbf02aec409f127b Maintainer: PhilDaiguille Status: ready -->
<!-- Reviewed: no Maintainer: Marqitos -->
<!-- EN-Revision: 50f76f26914c5a9e61aa26f2e36c4acb362a48fd Maintainer: PhilDaiguille Status: ready -->
<!-- Reviewed: no -->
<sect1 xml:id="language.types.void">
<title>Void</title>

<para>
<type>void</type> es una declaración de tipo de retorno únicamente, indicando que la función
no devuelve ningún valor, pero que la función puede terminar de todos modos.
Por lo tanto, no puede formar parte de una declaración de
<link linkend="language.types.type-system.composite.union">tipo de unión</link>
<type>void</type> es un tipo de declaración de retorno que indica que la
función no devuelve ningún valor, pero la función aún puede terminar.
Por lo tanto, no puede formar parte de una
<link linkend="language.types.type-system.composite.union">declaración de tipo unión</link>.
Disponible a partir de PHP 7.1.0.
</para>

<note>
<simpara>
Aunque una función tenga un tipo de retorno <type>void</type>, siempre
devolverá un valor, este valor siempre es &null;.
Incluso si una función tiene un tipo de retorno <type>void</type>, seguirá
devolviendo un valor; este valor siempre es &null;.
</simpara>
</note>

<sect2 xml:id="language.types.void.casting">
<title>Descartar un valor con <literal>(void)</literal></title>

<simpara>
La sintaxis <literal>(void)</literal> puede usarse para descartar
explícitamente el resultado de una expresión. Esto es útil para indicar que
ignorar un valor de retorno es intencional, especialmente al llamar a una
función o método marcado con el atributo <classname>NoDiscard</classname>.
</simpara>

<simpara>
A diferencia de otros moldes, <literal>(void)</literal> no convierte el
valor a otro tipo ni produce un valor. Es una sentencia y no puede usarse
como parte de una expresión.
</simpara>

<example>
<title>Descartar un valor de retorno</title>
<programlisting role="php" annotations="non-interactive">
<![CDATA[
<?php
#[\NoDiscard]
function process(): bool {
return true;
}

(void) process(); // Descartar explícitamente el valor de retorno
?>
]]>
</programlisting>
</example>
</sect2>
</sect1>
<!-- Keep this comment at the end of the file
Local variables:
Expand All @@ -37,6 +69,6 @@ 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
vim: et tw=78 syn=xml
vi: ts=1 sw=1
-->
16 changes: 7 additions & 9 deletions reference/mongodb/bson/utcdatetime/jsonserialize.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,12 +1,10 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 66d301903b063375c1618d754f1570a9d38746e3 Maintainer: PhilDaiguille Status: ready -->
<!-- EN-Revision: 9f4cb232d01a06077a2324e38f767d63f87f2e5f Maintainer: PhilDaiguille Status: ready -->
<!-- Reviewed: no -->

<refentry xml:id="mongodb-bson-utcdatetime.jsonserialize" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>MongoDB\BSON\UTCDateTime::jsonSerialize</refname>
<refpurpose>Devuelve una representación que puede ser convertida en JSON</refpurpose>
<refpurpose>Devuelve una representación que puede convertirse a JSON</refpurpose>
</refnamediv>

<refsect1 role="description">
Expand All @@ -24,11 +22,11 @@

<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Devuelve datos que pueden ser serializados por <function>json_encode</function>
para producir una representación JSON extendida de
<simpara>
Devuelve datos que pueden ser serializados por <function>json_encode</function> para
producir una representación JSON extendida de la
<classname>MongoDB\BSON\UTCDateTime</classname>.
</para>
</simpara>
&mongodb.note.extended-json;
</refsect1>

Expand All @@ -46,7 +44,7 @@
<member><function>json_encode</function></member>
<member><function>MongoDB\BSON\toCanonicalExtendedJSON</function></member>
<member><function>MongoDB\BSON\toRelaxedExtendedJSON</function></member>
<member><link xlink:href="&url.mongodb.docs.extendedjson;">MongoDB JSON Extendido</link></member>
<member><link xlink:href="&url.mongodb.docs.extendedjson;">MongoDB Extended JSON</link></member>
</simplelist>
</refsect1>

Expand Down
19 changes: 9 additions & 10 deletions reference/mongodb/bson/utcdatetime/todatetime.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,6 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: c9ff64ac878c34562858be79626e533a1ccaf072 Maintainer: PhilDaiguille Status: ready -->
<!-- EN-Revision: 9f4cb232d01a06077a2324e38f767d63f87f2e5f Maintainer: PhilDaiguille Status: ready -->
<!-- Reviewed: no -->

<refentry xml:id="mongodb-bson-utcdatetime.todatetime" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>MongoDB\BSON\UTCDateTime::toDateTime</refname>
Expand All @@ -12,7 +10,7 @@
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>final</modifier> <modifier>public</modifier> <type>DateTime</type><methodname>MongoDB\BSON\UTCDatetime::toDateTime</methodname>
<modifier>final</modifier> <modifier>public</modifier> <type>DateTime</type><methodname>MongoDB\BSON\UTCDateTime::toDateTime</methodname>
<void />
</methodsynopsis>
</refsect1>
Expand All @@ -24,10 +22,11 @@

<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Devuelve la representación <classname>DateTime</classname> de este UTCDateTime.
El <classname>DateTime</classname> devuelto utilizará el huso horario UTC.
</para>
<simpara>
Devuelve la representación <classname>DateTime</classname> de este
UTCDateTime. El <classname>DateTime</classname> devuelto utilizará la zona
horaria UTC.
</simpara>
</refsect1>

<refsect1 role="errors">
Expand All @@ -40,7 +39,7 @@
<refsect1 role="examples">
&reftitle.examples;
<example>
<title>Ejemplo con <function>MongoDB\BSON\UTCDatetime::toDateTime</function></title>
<title>Ejemplo de <function>MongoDB\BSON\UTCDatetime::toDateTime</function></title>
<programlisting role="php">
<![CDATA[
<?php
Expand Down Expand Up @@ -74,7 +73,7 @@ object(DateTimeZone)#3 (2) {
&reftitle.seealso;
<simplelist>
<member><methodname>MongoDB\BSON\UTCDateTime::toDateTimeImmutable</methodname></member>
<member><link xlink:href="&url.mongodb.docs.bson;#date">El tipo BSON : Date</link></member>
<member><link xlink:href="&url.mongodb.docs.bson;#date">Tipos BSON: Fecha</link></member>
</simplelist>
</refsect1>

Expand Down
16 changes: 8 additions & 8 deletions reference/mongodb/bson/utcdatetime/todatetimeimmutable.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: c9ff64ac878c34562858be79626e533a1ccaf072 Maintainer: PhilDaiguille Status: ready -->
<!-- EN-Revision: 9f4cb232d01a06077a2324e38f767d63f87f2e5f Maintainer: PhilDaiguille Status: ready -->
<!-- Reviewed: no -->
<refentry xml:id="mongodb-bson-utcdatetime.todatetimeimmutable" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>MongoDB\BSON\UTCDateTime::toDateTimeImmutable</refname>
<refpurpose>Devuelve la representación DateTimeImmutable de esta UTCDateTime</refpurpose>
<refpurpose>Devuelve la representación DateTimeImmutable de este UTCDateTime</refpurpose>
</refnamediv>

<refsect1 role="description">
Expand All @@ -22,11 +22,11 @@

<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Devuelve la representación <classname>DateTimeImmutable</classname> de esta
UTCDateTime. El <classname>DateTimeImmutable</classname> devuelto utilizará
el huso horario UTC.
</para>
<simpara>
Devuelve la representación <classname>DateTimeImmutable</classname> de este
UTCDateTime. El <classname>DateTimeImmutable</classname> devuelto utilizará la zona
horaria UTC.
</simpara>
</refsect1>

<refsect1 role="errors">
Expand Down Expand Up @@ -73,7 +73,7 @@ object(DateTimeZone)#3 (2) {
&reftitle.seealso;
<simplelist>
<member><methodname>MongoDB\BSON\UTCDateTime::toDateTime</methodname></member>
<member><link xlink:href="&url.mongodb.docs.bson;#date">Tipos BSON : Date</link></member>
<member><link xlink:href="&url.mongodb.docs.bson;#date">Tipos BSON: Fecha</link></member>
</simplelist>
</refsect1>

Expand Down
12 changes: 5 additions & 7 deletions reference/mongodb/bson/utcdatetime/tostring.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,6 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 6ff13d6d3795fd73f8dd57ee92743b967c5fd0d0 Maintainer: PhilDaiguille Status: ready -->
<!-- EN-Revision: 9f4cb232d01a06077a2324e38f767d63f87f2e5f Maintainer: PhilDaiguille Status: ready -->
<!-- Reviewed: no -->

<refentry xml:id="mongodb-bson-utcdatetime.tostring" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>MongoDB\BSON\UTCDateTime::__toString</refname>
Expand All @@ -24,15 +22,15 @@

<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
<simpara>
Devuelve la representación en forma de string de este UTCDateTime.
</para>
</simpara>
</refsect1>

<refsect1 role="examples">
&reftitle.examples;
<example>
<title>Ejemplo con <function>MongoDB\BSON\UTCDatetime::__toString</function></title>
<title>Ejemplo de <function>MongoDB\BSON\UTCDateTime::__toString</function></title>
<programlisting role="php">
<![CDATA[
<?php
Expand All @@ -55,7 +53,7 @@ string(13) "1416445411987"
<refsect1 role="seealso">
&reftitle.seealso;
<simplelist>
<member><link xlink:href="&url.mongodb.docs.bson;#date">BSON Types: Date</link></member>
<member><link xlink:href="&url.mongodb.docs.bson;#date">Tipos BSON: Fecha</link></member>
</simplelist>
</refsect1>

Expand Down
14 changes: 6 additions & 8 deletions reference/mongodb/bson/utcdatetimeinterface/todatetime.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,12 +1,10 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: e9366ee458b2900c53a503b1ad97664e1d9a8859 Maintainer: PhilDaiguille Status: ready -->
<!-- EN-Revision: 9f4cb232d01a06077a2324e38f767d63f87f2e5f Maintainer: PhilDaiguille Status: ready -->
<!-- Reviewed: no -->

<refentry xml:id="mongodb-bson-utcdatetimeinterface.todatetime" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>MongoDB\BSON\UTCDateTimeInterface::toDateTime</refname>
<refpurpose>Devuelve la representación DateTime de UTCDateTimeInterface</refpurpose>
<refpurpose>Devuelve la representación DateTime de esta UTCDateTimeInterface</refpurpose>
</refnamediv>

<refsect1 role="description">
Expand All @@ -24,11 +22,11 @@

<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
<simpara>
Devuelve la representación <classname>DateTime</classname> de esta
UTCDateTimeInterface. El <classname>DateTime</classname> debería utilizar
el huso horario UTC.
</para>
UTCDateTimeInterface. El <classname>DateTime</classname> devuelto debe usar
la zona horaria UTC.
</simpara>
</refsect1>

<refsect1 role="seealso">
Expand Down
11 changes: 5 additions & 6 deletions reference/mongodb/bson/utcdatetimeinterface/todatetimeimmutable.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,10 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 4639881688d3faaf0073ad71fe0a4b730aea15a0 Maintainer: PhilDaiguille Status: ready -->
<!-- EN-Revision: 9f4cb232d01a06077a2324e38f767d63f87f2e5f Maintainer: PhilDaiguille Status: ready -->
<!-- Reviewed: no -->

<refentry xml:id="mongodb-bson-utcdatetimeinterface.todatetimeimmutable" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>MongoDB\BSON\UTCDateTimeInterface::toDateTimeImmutable</refname>
<refpurpose>Devuelve la representación DateTimeImmutable de esta UTCDateTimeInterface</refpurpose>
<refpurpose>Devuelve la representación DateTimeImmutable de esta interfaz UTCDateTimeInterface</refpurpose>
</refnamediv>

<refsect1 role="description">
Expand All @@ -23,10 +22,10 @@

<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
<simpara>
Devuelve la representación <classname>DateTimeImmutable</classname> de esta
UTCDateTimeInterface. La <classname>DateTimeImmutable</classname> devuelta utilizará la zona horaria UTC.
</para>
interfaz UTCDateTimeInterface. El <classname>DateTimeImmutable</classname> devuelto utilizará la zona horaria UTC.
</simpara>
</refsect1>

<refsect1 role="seealso">
Expand Down
12 changes: 5 additions & 7 deletions reference/mongodb/bson/utcdatetimeinterface/tostring.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,12 +1,10 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: e9366ee458b2900c53a503b1ad97664e1d9a8859 Maintainer: PhilDaiguille Status: ready -->
<!-- EN-Revision: 9f4cb232d01a06077a2324e38f767d63f87f2e5f Maintainer: PhilDaiguille Status: ready -->
<!-- Reviewed: no -->

<refentry xml:id="mongodb-bson-utcdatetimeinterface.tostring" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>MongoDB\BSON\UTCDateTimeInterface::__toString</refname>
<refpurpose>Devuelve la representación en forma de string de UTCDateTimeInterface</refpurpose>
<refpurpose>Devuelve la representación en string de esta UTCDateTimeInterface</refpurpose>
</refnamediv>

<refsect1 role="description">
Expand All @@ -24,9 +22,9 @@

<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Devuelve la representación en forma de string de UTCDateTimeInterface.
</para>
<simpara>
Devuelve la representación en string de esta UTCDateTimeInterface.
</simpara>
</refsect1>

<refsect1 role="seealso">
Expand Down
Loading
Loading