Skip to content

Commit ddb05f8

Browse files
SakiTakamachiGirgiasnielsdos
authored
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 <[email protected]> Co-authored-by: Niels Dossche <[email protected]>
1 parent 781f2ec commit ddb05f8

File tree

15 files changed

+143
-215
lines changed

15 files changed

+143
-215
lines changed

‎language-snippets.ent

Lines changed: 11 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -2149,11 +2149,17 @@ extensions in order to use these functions.</simpara>'>
21492149
<!ENTITY sqlsafemode '<link xmlns="http://docbook.org/ns/docbook" linkend="ini.sql.safe-mode">SQL safe mode</link>'>
21502150

21512151
<!-- BCMath Notes -->
2152-
<!ENTITY bc.scale.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
2153-
<parameter>scale</parameter></term><listitem><para>This optional parameter is used to set the number
2154-
of digits after the decimal place in the result. If omitted, it will default to the scale set
2155-
globally with the <function>bcscale</function> function, or fallback to <literal>0</literal> if
2156-
this has not been set.</para></listitem></varlistentry>'>
2152+
<!ENTITY bc.scale.description '<varlistentry xmlns="http://docbook.org/ns/docbook">
2153+
<term><parameter>scale</parameter></term>
2154+
<listitem>
2155+
<simpara>
2156+
This parameter is used to set the number of digits after the decimal place in the result.
2157+
If &null;, it will default to the default scale set with <function>bcscale</function>,
2158+
or fallback to the value of the
2159+
<link linkend="ini.bcmath.scale"><literal>bcmath.scale</literal></link> INI directive.
2160+
</simpara>
2161+
</listitem>
2162+
</varlistentry>'>
21572163

21582164
<!-- CTYPE Notes -->
21592165
<!ENTITY note.ctype.parameter.integer '<note xmlns="http://docbook.org/ns/docbook"><para>

‎reference/bc/functions/bcadd.xml

Lines changed: 17 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -51,7 +51,23 @@
5151
The sum of the two operands, as a string.
5252
</para>
5353
</refsect1>
54-
54+
55+
<refsect1 role="errors">
56+
&reftitle.errors;
57+
<para>
58+
This function throws a <exceptionname>ValueError</exceptionname> in the following cases:
59+
<simplelist>
60+
<member>
61+
<parameter>num1</parameter> or <parameter>num2</parameter>
62+
is not a well-formed BCMath numeric string.
63+
</member>
64+
<member>
65+
<parameter>scale</parameter> is outside the valid range.
66+
</member>
67+
</simplelist>
68+
</para>
69+
</refsect1>
70+
5571
<refsect1 role="changelog">
5672
&reftitle.changelog;
5773
<informaltable>

‎reference/bc/functions/bcceil.xml

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,14 @@
3939
</simpara>
4040
</refsect1>
4141

42+
<refsect1 role="errors">
43+
&reftitle.errors;
44+
<simpara>
45+
This function throws a <exceptionname>ValueError</exceptionname> if
46+
<parameter>num</parameter> is not a well-formed BCMath numeric string.
47+
</simpara>
48+
</refsect1>
49+
4250
<refsect1 role="examples">
4351
&reftitle.examples;
4452
<example>

‎reference/bc/functions/bccomp.xml

Lines changed: 12 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
<?xml version="1.0" encoding="utf-8"?>
22
<!-- $Revision$ -->
3-
<refentry xml:id="function.bccomp" xmlns="http://docbook.org/ns/docbook">
3+
<refentry xml:id="function.bccomp" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude">
44
<refnamediv>
55
<refname>bccomp</refname>
66
<refpurpose>Compare two arbitrary precision numbers</refpurpose>
@@ -15,55 +15,26 @@
1515
<methodparam choice="opt"><type class="union"><type>int</type><type>null</type></type><parameter>scale</parameter><initializer>&null;</initializer></methodparam>
1616
</methodsynopsis>
1717
<para>
18-
Compares the <parameter>num1</parameter> to the
19-
<parameter>num2</parameter> and returns the result as an
20-
integer.
18+
Compares <parameter>num1</parameter> to <parameter>num2</parameter>
19+
and returns the result of the comparison as an integer.
2120
</para>
2221
</refsect1>
2322

2423
<refsect1 role="parameters">
25-
&reftitle.parameters;
26-
<para>
27-
<variablelist>
28-
<varlistentry>
29-
<term><parameter>num1</parameter></term>
30-
<listitem>
31-
<para>
32-
The left operand, as a string.
33-
</para>
34-
</listitem>
35-
</varlistentry>
36-
<varlistentry>
37-
<term><parameter>num2</parameter></term>
38-
<listitem>
39-
<para>
40-
The right operand, as a string.
41-
</para>
42-
</listitem>
43-
</varlistentry>
44-
<varlistentry>
45-
<term><parameter>scale</parameter></term>
46-
<listitem>
47-
<para>
48-
The optional <parameter>scale</parameter> parameter is used to set the
49-
number of digits after the decimal place which will be used in the
50-
comparison.
51-
</para>
52-
</listitem>
53-
</varlistentry>
54-
</variablelist>
55-
</para>
24+
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('function.bcadd')/db:refsect1[@role='parameters']/*)" />
5625
</refsect1>
5726

5827
<refsect1 role="returnvalues">
5928
&reftitle.returnvalues;
60-
<para>
61-
Returns 0 if the two operands are equal, 1 if the
62-
<parameter>num1</parameter> is larger than the
63-
<parameter>num2</parameter>, -1 otherwise.
64-
</para>
29+
<simpara>
30+
Returns <literal>0</literal> if both operands are equal,
31+
<literal>1</literal> if <parameter>num1</parameter> is greater than
32+
<parameter>num2</parameter>, <literal>-1</literal> otherwise.
33+
</simpara>
6534
</refsect1>
66-
35+
36+
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('function.bcadd')/db:refsect1[@role='errors'])" />
37+
6738
<refsect1 role="changelog">
6839
&reftitle.changelog;
6940
<informaltable>

‎reference/bc/functions/bcdiv.xml

Lines changed: 11 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
<?xml version="1.0" encoding="utf-8"?>
22
<!-- $Revision$ -->
3-
<refentry xml:id="function.bcdiv" xmlns="http://docbook.org/ns/docbook">
3+
<refentry xml:id="function.bcdiv" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude">
44
<refnamediv>
55
<refname>bcdiv</refname>
66
<refpurpose>Divide two arbitrary precision numbers</refpurpose>
@@ -14,10 +14,9 @@
1414
<methodparam><type>string</type><parameter>num2</parameter></methodparam>
1515
<methodparam choice="opt"><type class="union"><type>int</type><type>null</type></type><parameter>scale</parameter><initializer>&null;</initializer></methodparam>
1616
</methodsynopsis>
17-
<para>
18-
Divides the <parameter>num1</parameter> by the
19-
<parameter>num2</parameter>.
20-
</para>
17+
<simpara>
18+
Divides <parameter>num1</parameter> by <parameter>num2</parameter>.
19+
</simpara>
2120
</refsect1>
2221

2322
<refsect1 role="parameters">
@@ -53,17 +52,11 @@
5352
</refsect1>
5453

5554
<refsect1 role="errors">
56-
&reftitle.errors;
57-
<para>
58-
This function throws a <exceptionname>ValueError</exceptionname> in the following cases:
59-
<simplelist>
60-
<member><parameter>num1</parameter> or <parameter>num2</parameter> is not a well-formed BCMath numeric string</member>
61-
<member><parameter>scale</parameter> is outside the valid range</member>
62-
</simplelist>
63-
</para>
55+
<!-- Include standard ValueErrors for num1, num2, and scale, this includes the title -->
56+
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('function.bcadd')/db:refsect1[@role='errors']/*)" />
6457
<simpara>
65-
This function throws a <exceptionname>DivisionByZeroError</exceptionname> exception if <parameter>num2</parameter>
66-
is <literal>0</literal>.
58+
This function throws a <exceptionname>DivisionByZeroError</exceptionname>
59+
exception if <parameter>num2</parameter> is <literal>0</literal>.
6760
</simpara>
6861
</refsect1>
6962

@@ -87,7 +80,9 @@
8780
<row>
8881
<entry>8.0.0</entry>
8982
<entry>
90-
Dividing by 0 now throws a <exceptionname>DivisionByZeroError</exceptionname> exception instead of returning null.
83+
Dividing by <literal>0</literal> now throws a
84+
<exceptionname>DivisionByZeroError</exceptionname> exception
85+
instead of returning &null;.
9186
</entry>
9287
</row>
9388
</tbody>

‎reference/bc/functions/bcdivmod.xml

Lines changed: 3 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
<?xml version="1.0" encoding="utf-8"?>
22
<!-- $Revision$ -->
3-
<refentry xml:id="function.bcdivmod" xmlns="http://docbook.org/ns/docbook">
3+
<refentry xml:id="function.bcdivmod" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude">
44
<refnamediv>
55
<refname>bcdivmod</refname>
66
<refpurpose>Get the quotient and modulus of an arbitrary precision number</refpurpose>
@@ -21,26 +21,7 @@
2121
</refsect1>
2222

2323
<refsect1 role="parameters">
24-
&reftitle.parameters;
25-
<variablelist>
26-
<varlistentry>
27-
<term><parameter>num1</parameter></term>
28-
<listitem>
29-
<simpara>
30-
The dividend, as a string.
31-
</simpara>
32-
</listitem>
33-
</varlistentry>
34-
<varlistentry>
35-
<term><parameter>num2</parameter></term>
36-
<listitem>
37-
<simpara>
38-
The divisor, as a string.
39-
</simpara>
40-
</listitem>
41-
</varlistentry>
42-
&bc.scale.description;
43-
</variablelist>
24+
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('function.bcdiv')/db:refsect1[@role='parameters']/*)" />
4425
</refsect1>
4526

4627
<refsect1 role="returnvalues">
@@ -51,20 +32,7 @@
5132
</simpara>
5233
</refsect1>
5334

54-
<refsect1 role="errors">
55-
&reftitle.errors;
56-
<para>
57-
This function throws a <exceptionname>ValueError</exceptionname> in the following cases:
58-
<simplelist>
59-
<member><parameter>num1</parameter> or <parameter>num2</parameter> is not a well-formed BCMath numeric string</member>
60-
<member><parameter>scale</parameter> is outside the valid range</member>
61-
</simplelist>
62-
</para>
63-
<simpara>
64-
This function throws a <exceptionname>DivisionByZeroError</exceptionname> exception if <parameter>num2</parameter>
65-
is <literal>0</literal>.
66-
</simpara>
67-
</refsect1>
35+
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('function.bcdiv')/db:refsect1[@role='errors'])" />
6836

6937
<refsect1 role="examples">
7038
&reftitle.examples;

‎reference/bc/functions/bcfloor.xml

Lines changed: 4 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
<?xml version="1.0" encoding="utf-8"?>
22
<!-- $Revision$ -->
3-
<refentry xml:id="function.bcfloor" xmlns="http://docbook.org/ns/docbook">
3+
<refentry xml:id="function.bcfloor" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude">
44
<refnamediv>
55
<refname>bcfloor</refname>
66
<refpurpose>Round down arbitrary precision number</refpurpose>
@@ -19,17 +19,7 @@
1919
</refsect1>
2020

2121
<refsect1 role="parameters">
22-
&reftitle.parameters;
23-
<variablelist>
24-
<varlistentry>
25-
<term><parameter>num</parameter></term>
26-
<listitem>
27-
<simpara>
28-
The value to round.
29-
</simpara>
30-
</listitem>
31-
</varlistentry>
32-
</variablelist>
22+
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('function.bcceil')/db:refsect1[@role='parameters']/*)" />
3323
</refsect1>
3424

3525
<refsect1 role="returnvalues">
@@ -39,6 +29,8 @@
3929
</simpara>
4030
</refsect1>
4131

32+
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('function.bcceil')/db:refsect1[@role='errors'])" />
33+
4234
<refsect1 role="examples">
4335
&reftitle.examples;
4436
<example>

‎reference/bc/functions/bcmod.xml

Lines changed: 5 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
<?xml version="1.0" encoding="utf-8"?>
22
<!-- $Revision$ -->
3-
<refentry xml:id="function.bcmod" xmlns="http://docbook.org/ns/docbook">
3+
<refentry xml:id="function.bcmod" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude">
44
<refnamediv>
55
<refname>bcmod</refname>
66
<refpurpose>Get modulus of an arbitrary precision number</refpurpose>
@@ -17,34 +17,12 @@
1717
<para>
1818
Get the remainder of dividing <parameter>num1</parameter> by
1919
<parameter>num2</parameter>.
20-
Unless <parameter>num2</parameter> is zero, the result has the same sign
21-
as <parameter>num1</parameter>.
20+
The result has the same sign as <parameter>num1</parameter>.
2221
</para>
2322
</refsect1>
2423

2524
<refsect1 role="parameters">
26-
&reftitle.parameters;
27-
<para>
28-
<variablelist>
29-
<varlistentry>
30-
<term><parameter>num1</parameter></term>
31-
<listitem>
32-
<para>
33-
The dividend, as a string.
34-
</para>
35-
</listitem>
36-
</varlistentry>
37-
<varlistentry>
38-
<term><parameter>num2</parameter></term>
39-
<listitem>
40-
<para>
41-
The divisor, as a string.
42-
</para>
43-
</listitem>
44-
</varlistentry>
45-
&bc.scale.description;
46-
</variablelist>
47-
</para>
25+
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('function.bcadd')/db:refsect1[@role='parameters']/*)" />
4826
</refsect1>
4927

5028
<refsect1 role="returnvalues">
@@ -54,20 +32,7 @@
5432
</para>
5533
</refsect1>
5634

57-
<refsect1 role="errors">
58-
&reftitle.errors;
59-
<para>
60-
This function throws a <exceptionname>ValueError</exceptionname> in the following cases:
61-
<simplelist>
62-
<member><parameter>num1</parameter> or <parameter>num2</parameter> is not a well-formed BCMath numeric string</member>
63-
<member><parameter>scale</parameter> is outside the valid range</member>
64-
</simplelist>
65-
</para>
66-
<simpara>
67-
This function throws a <exceptionname>DivisionByZeroError</exceptionname> exception if <parameter>num2</parameter>
68-
is <literal>0</literal>.
69-
</simpara>
70-
</refsect1>
35+
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('function.bcdiv')/db:refsect1[@role='errors'])" />
7136

7237
<refsect1 role="changelog"><!-- {{{ -->
7338
&reftitle.changelog;
@@ -89,7 +54,7 @@
8954
<row>
9055
<entry>8.0.0</entry>
9156
<entry>
92-
Dividing by 0 now throws a <exceptionname>DivisionByZeroError</exceptionname> exception instead of returning null.
57+
Dividing by <literal>0</literal> now throws a <exceptionname>DivisionByZeroError</exceptionname> exception instead of returning null.
9358
</entry>
9459
</row>
9560
<row>

0 commit comments

Comments
 (0)