ext/bcmath: Improve documentation for BCMath (#4163)

- Use XIncludes to reduce duplications - Add error sections - Fix description of the scale parameter. - Wording improvements --------- Co-authored-by: Gina Peter Banyard <girgias@php.net> Co-authored-by: Niels Dossche <7771979+nielsdos@users.noreply.github.com>
php · Dec 1, 2024 · ddb05f8 · ddb05f8
1 parent 781f2ec
commit ddb05f8
Show file tree

Hide file tree

Showing 15 changed files with 143 additions and 215 deletions.
diff --git a/language-snippets.ent b/language-snippets.ent
@@ -2149,11 +2149,17 @@ extensions in order to use these functions.</simpara>'>
 <!ENTITY sqlsafemode '<link xmlns="http://docbook.org/ns/docbook" linkend="ini.sql.safe-mode">SQL safe mode</link>'>
 
 <!-- BCMath Notes -->
-<!ENTITY bc.scale.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
-<parameter>scale</parameter></term><listitem><para>This optional parameter is used to set the number
-of digits after the decimal place in the result. If omitted, it will default to the scale set
-globally with the <function>bcscale</function> function, or fallback to <literal>0</literal> if
-this has not been set.</para></listitem></varlistentry>'>
+<!ENTITY bc.scale.description '<varlistentry xmlns="http://docbook.org/ns/docbook">
+ <term><parameter>scale</parameter></term>
+ <listitem>
+  <simpara>
+   This parameter is used to set the number of digits after the decimal place in the result.
+   If &null;, it will default to the default scale set with <function>bcscale</function>,
+   or fallback to the value of the
+   <link linkend="ini.bcmath.scale"><literal>bcmath.scale</literal></link> INI directive.
+  </simpara>
+ </listitem>
+</varlistentry>'>
 
 <!-- CTYPE Notes -->
 <!ENTITY note.ctype.parameter.integer '<note xmlns="http://docbook.org/ns/docbook"><para>

diff --git a/reference/bc/functions/bcadd.xml b/reference/bc/functions/bcadd.xml
@@ -51,7 +51,23 @@
    The sum of the two operands, as a string.
   </para>
  </refsect1>
-
+
+ <refsect1 role="errors">
+  &reftitle.errors;
+  <para>
+   This function throws a <exceptionname>ValueError</exceptionname> in the following cases:
+   <simplelist>
+    <member>
+     <parameter>num1</parameter> or <parameter>num2</parameter>
+     is not a well-formed BCMath numeric string.
+    </member>
+    <member>
+     <parameter>scale</parameter> is outside the valid range.
+    </member>
+   </simplelist>
+  </para>
+ </refsect1>
+
  <refsect1 role="changelog">
   &reftitle.changelog;
   <informaltable>

diff --git a/reference/bc/functions/bcceil.xml b/reference/bc/functions/bcceil.xml
@@ -39,6 +39,14 @@
   </simpara>
  </refsect1>
 
+ <refsect1 role="errors">
+  &reftitle.errors;
+  <simpara>
+   This function throws a <exceptionname>ValueError</exceptionname> if
+   <parameter>num</parameter> is not a well-formed BCMath numeric string.
+  </simpara>
+ </refsect1>
+
  <refsect1 role="examples">
   &reftitle.examples;
   <example>

diff --git a/reference/bc/functions/bccomp.xml b/reference/bc/functions/bccomp.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<refentry xml:id="function.bccomp" xmlns="http://docbook.org/ns/docbook">
+<refentry xml:id="function.bccomp" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude">
  <refnamediv>
   <refname>bccomp</refname>
   <refpurpose>Compare two arbitrary precision numbers</refpurpose>
@@ -15,55 +15,26 @@
    <methodparam choice="opt"><type class="union"><type>int</type><type>null</type></type><parameter>scale</parameter><initializer>&null;</initializer></methodparam>
   </methodsynopsis>
   <para>
-   Compares the <parameter>num1</parameter> to the
-   <parameter>num2</parameter> and returns the result as an
-   integer.  
+   Compares <parameter>num1</parameter> to <parameter>num2</parameter>
+   and returns the result of the comparison as an integer.
   </para>
  </refsect1>
 
  <refsect1 role="parameters">
-  &reftitle.parameters;
-  <para>
-   <variablelist>
-    <varlistentry>
-     <term><parameter>num1</parameter></term>
-     <listitem>
-      <para>
-       The left operand, as a string.
-      </para>
-     </listitem>
-    </varlistentry>
-    <varlistentry>
-     <term><parameter>num2</parameter></term>
-     <listitem>
-      <para>
-       The right operand, as a string.
-      </para>
-     </listitem>
-    </varlistentry>
-    <varlistentry>
-     <term><parameter>scale</parameter></term>
-     <listitem>
-      <para>
-       The optional <parameter>scale</parameter> parameter is used to set the
-       number of digits after the decimal place which will be used in the
-       comparison.  
-      </para>
-     </listitem>
-    </varlistentry>
-   </variablelist>
-  </para>
+  <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('function.bcadd')/db:refsect1[@role='parameters']/*)" />
  </refsect1>
 
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
-  <para>
-   Returns 0 if the two operands are equal, 1 if the
-   <parameter>num1</parameter> is larger than the 
-   <parameter>num2</parameter>, -1 otherwise.
-  </para>
+  <simpara>
+   Returns <literal>0</literal> if both operands are equal,
+   <literal>1</literal> if <parameter>num1</parameter> is greater than
+   <parameter>num2</parameter>, <literal>-1</literal> otherwise.
+  </simpara>
  </refsect1>
-
+
+ <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('function.bcadd')/db:refsect1[@role='errors'])" />
+
  <refsect1 role="changelog">
   &reftitle.changelog;
   <informaltable>

diff --git a/reference/bc/functions/bcdiv.xml b/reference/bc/functions/bcdiv.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<refentry xml:id="function.bcdiv" xmlns="http://docbook.org/ns/docbook">
+<refentry xml:id="function.bcdiv" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude">
  <refnamediv>
   <refname>bcdiv</refname>
   <refpurpose>Divide two arbitrary precision numbers</refpurpose>
@@ -14,10 +14,9 @@
    <methodparam><type>string</type><parameter>num2</parameter></methodparam>
    <methodparam choice="opt"><type class="union"><type>int</type><type>null</type></type><parameter>scale</parameter><initializer>&null;</initializer></methodparam>
   </methodsynopsis>
-  <para>
-   Divides the <parameter>num1</parameter> by the
-   <parameter>num2</parameter>.
-  </para>
+  <simpara>
+   Divides <parameter>num1</parameter> by <parameter>num2</parameter>.
+  </simpara>
  </refsect1>
 
  <refsect1 role="parameters">
@@ -53,17 +52,11 @@
  </refsect1>
 
  <refsect1 role="errors">
-  &reftitle.errors;
-  <para>
-   This function throws a <exceptionname>ValueError</exceptionname> in the following cases:
-   <simplelist>
-    <member><parameter>num1</parameter> or <parameter>num2</parameter> is not a well-formed BCMath numeric string</member>
-    <member><parameter>scale</parameter> is outside the valid range</member>
-   </simplelist>
-  </para>
+  <!-- Include standard ValueErrors for num1, num2, and scale, this includes the title -->
+  <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('function.bcadd')/db:refsect1[@role='errors']/*)" />
   <simpara>
-   This function throws a <exceptionname>DivisionByZeroError</exceptionname> exception if <parameter>num2</parameter>
-   is <literal>0</literal>.
+   This function throws a <exceptionname>DivisionByZeroError</exceptionname>
+   exception if <parameter>num2</parameter> is <literal>0</literal>.
   </simpara>
  </refsect1>
 
@@ -87,7 +80,9 @@
      <row>
       <entry>8.0.0</entry>
       <entry>
-       Dividing by 0 now throws a <exceptionname>DivisionByZeroError</exceptionname> exception instead of returning null.
+       Dividing by <literal>0</literal> now throws a
+       <exceptionname>DivisionByZeroError</exceptionname> exception
+       instead of returning &null;.
       </entry>
      </row>
     </tbody>

diff --git a/reference/bc/functions/bcdivmod.xml b/reference/bc/functions/bcdivmod.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<refentry xml:id="function.bcdivmod" xmlns="http://docbook.org/ns/docbook">
+<refentry xml:id="function.bcdivmod" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude">
  <refnamediv>
   <refname>bcdivmod</refname>
   <refpurpose>Get the quotient and modulus of an arbitrary precision number</refpurpose>
@@ -21,26 +21,7 @@
  </refsect1>
 
  <refsect1 role="parameters">
-  &reftitle.parameters;
-  <variablelist>
-   <varlistentry>
-    <term><parameter>num1</parameter></term>
-    <listitem>
-     <simpara>
-      The dividend, as a string.
-     </simpara>
-    </listitem>
-   </varlistentry>
-   <varlistentry>
-    <term><parameter>num2</parameter></term>
-    <listitem>
-     <simpara>
-      The divisor, as a string.
-     </simpara>
-    </listitem>
-   </varlistentry>
-   &bc.scale.description;
-  </variablelist>
+  <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('function.bcdiv')/db:refsect1[@role='parameters']/*)" />
  </refsect1>
 
  <refsect1 role="returnvalues">
@@ -51,20 +32,7 @@
   </simpara>
  </refsect1>
 
- <refsect1 role="errors">
-  &reftitle.errors;
-  <para>
-   This function throws a <exceptionname>ValueError</exceptionname> in the following cases:
-   <simplelist>
-    <member><parameter>num1</parameter> or <parameter>num2</parameter> is not a well-formed BCMath numeric string</member>
-    <member><parameter>scale</parameter> is outside the valid range</member>
-   </simplelist>
-  </para>
-  <simpara>
-   This function throws a <exceptionname>DivisionByZeroError</exceptionname> exception if <parameter>num2</parameter>
-   is <literal>0</literal>.
-  </simpara>
- </refsect1>
+ <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('function.bcdiv')/db:refsect1[@role='errors'])" />
 
  <refsect1 role="examples">
   &reftitle.examples;

diff --git a/reference/bc/functions/bcfloor.xml b/reference/bc/functions/bcfloor.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<refentry xml:id="function.bcfloor" xmlns="http://docbook.org/ns/docbook">
+<refentry xml:id="function.bcfloor" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude">
  <refnamediv>
   <refname>bcfloor</refname>
   <refpurpose>Round down arbitrary precision number</refpurpose>
@@ -19,17 +19,7 @@
  </refsect1>
 
  <refsect1 role="parameters">
-  &reftitle.parameters;
-  <variablelist>
-   <varlistentry>
-    <term><parameter>num</parameter></term>
-    <listitem>
-     <simpara>
-      The value to round.
-     </simpara>
-    </listitem>
-   </varlistentry>
-  </variablelist>
+  <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('function.bcceil')/db:refsect1[@role='parameters']/*)" />
  </refsect1>
 
  <refsect1 role="returnvalues">
@@ -39,6 +29,8 @@
   </simpara>
  </refsect1>
 
+ <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('function.bcceil')/db:refsect1[@role='errors'])" />
+
  <refsect1 role="examples">
   &reftitle.examples;
   <example>

diff --git a/reference/bc/functions/bcmod.xml b/reference/bc/functions/bcmod.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<refentry xml:id="function.bcmod" xmlns="http://docbook.org/ns/docbook">
+<refentry xml:id="function.bcmod" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude">
  <refnamediv>
   <refname>bcmod</refname>
   <refpurpose>Get modulus of an arbitrary precision number</refpurpose>
@@ -17,34 +17,12 @@
   <para>
    Get the remainder of dividing <parameter>num1</parameter> by
    <parameter>num2</parameter>.
-   Unless <parameter>num2</parameter> is zero, the result has the same sign
-   as <parameter>num1</parameter>.
+   The result has the same sign as <parameter>num1</parameter>.
   </para>
  </refsect1>
 
  <refsect1 role="parameters">
-  &reftitle.parameters;
-  <para>
-   <variablelist>
-    <varlistentry>
-     <term><parameter>num1</parameter></term>
-     <listitem>
-      <para>
-       The dividend, as a string.
-      </para>
-     </listitem>
-    </varlistentry>
-    <varlistentry>
-     <term><parameter>num2</parameter></term>
-     <listitem>
-      <para>
-       The divisor, as a string.
-      </para>
-     </listitem>
-    </varlistentry>
-    &bc.scale.description;
-   </variablelist>
-  </para>
+  <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('function.bcadd')/db:refsect1[@role='parameters']/*)" />
  </refsect1>
 
  <refsect1 role="returnvalues">
@@ -54,20 +32,7 @@
   </para>
  </refsect1>
 
- <refsect1 role="errors">
-  &reftitle.errors;
-  <para>
-   This function throws a <exceptionname>ValueError</exceptionname> in the following cases:
-   <simplelist>
-    <member><parameter>num1</parameter> or <parameter>num2</parameter> is not a well-formed BCMath numeric string</member>
-    <member><parameter>scale</parameter> is outside the valid range</member>
-   </simplelist>
-  </para>
-  <simpara>
-   This function throws a <exceptionname>DivisionByZeroError</exceptionname> exception if <parameter>num2</parameter>
-   is <literal>0</literal>.
-  </simpara>
- </refsect1>
+ <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('function.bcdiv')/db:refsect1[@role='errors'])" />
 
  <refsect1 role="changelog"><!-- {{{ -->
   &reftitle.changelog;
@@ -89,7 +54,7 @@
      <row>
       <entry>8.0.0</entry>
       <entry>
-       Dividing by 0 now throws a <exceptionname>DivisionByZeroError</exceptionname> exception instead of returning null.
+       Dividing by <literal>0</literal> now throws a <exceptionname>DivisionByZeroError</exceptionname> exception instead of returning null.
       </entry>
      </row>
      <row>