From f922f1a7e5c5f07c6bbacc4466ff0ab0329a2394 Mon Sep 17 00:00:00 2001
From: Christoph Michael Becker <cmb@php.net>
Date: Sat, 9 Sep 2017 12:29:42 +0000
Subject: [PATCH] Improve documentation of bcpow() and bcpowmod()

We clarify the meaning of $left_operand and $right_operand,
and also document the supported values.

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@343026 c90b9560-bf6c-de11-be94-00142212c4b1
---
 reference/bc/functions/bcpow.xml    | 18 ++++++++++--------
 reference/bc/functions/bcpowmod.xml | 20 ++++++++++----------
 2 files changed, 20 insertions(+), 18 deletions(-)

diff --git a/reference/bc/functions/bcpow.xml b/reference/bc/functions/bcpow.xml
index e06658053c..0ef30df00d 100644
--- a/reference/bc/functions/bcpow.xml
+++ b/reference/bc/functions/bcpow.xml
@@ -10,13 +10,13 @@
   &reftitle.description;
   <methodsynopsis>
    <type>string</type><methodname>bcpow</methodname>
-   <methodparam><type>string</type><parameter>left_operand</parameter></methodparam>
-   <methodparam><type>string</type><parameter>right_operand</parameter></methodparam>
+   <methodparam><type>string</type><parameter>base</parameter></methodparam>
+   <methodparam><type>string</type><parameter>exponent</parameter></methodparam>
    <methodparam choice="opt"><type>int</type><parameter>scale</parameter><initializer>0</initializer></methodparam>
   </methodsynopsis>
   <para>
-   Raise <parameter>left_operand</parameter> to the power 
-   <parameter>right_operand</parameter>. 
+   Raise <parameter>base</parameter> to the power 
+   <parameter>exponent</parameter>. 
   </para>
  </refsect1>
 
@@ -25,18 +25,20 @@
   <para>
    <variablelist>
     <varlistentry>
-     <term><parameter>left_operand</parameter></term>
+     <term><parameter>base</parameter></term>
      <listitem>
       <para>
-       The left operand, as a string.
+       The base, as a string.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
-     <term><parameter>right_operand</parameter></term>
+     <term><parameter>exponent</parameter></term>
      <listitem>
       <para>
-       The right operand, as a string.
+       The exponent, as a string. If the exponent is non-integral, it is truncated.
+       The valid range of the exponent is platform specific, but is at least
+       <literal>-2147483648</literal> to <literal>2147483647</literal>.
       </para>
      </listitem>
     </varlistentry>
diff --git a/reference/bc/functions/bcpowmod.xml b/reference/bc/functions/bcpowmod.xml
index 36b605c51f..dad905c8ee 100644
--- a/reference/bc/functions/bcpowmod.xml
+++ b/reference/bc/functions/bcpowmod.xml
@@ -10,15 +10,15 @@
   &reftitle.description;
   <methodsynopsis>
    <type>string</type><methodname>bcpowmod</methodname>
-   <methodparam><type>string</type><parameter>left_operand</parameter></methodparam>
-   <methodparam><type>string</type><parameter>right_operand</parameter></methodparam>
+   <methodparam><type>string</type><parameter>base</parameter></methodparam>
+   <methodparam><type>string</type><parameter>exponent</parameter></methodparam>
    <methodparam><type>string</type><parameter>modulus</parameter></methodparam>
    <methodparam choice="opt"><type>int</type><parameter>scale</parameter><initializer>0</initializer></methodparam>
   </methodsynopsis>
   <para>
    Use the fast-exponentiation method to raise 
-   <parameter>left_operand</parameter> to the power
-   <parameter>right_operand</parameter> with respect to the modulus
+   <parameter>base</parameter> to the power
+   <parameter>exponent</parameter> with respect to the modulus
    <parameter>modulus</parameter>.
   </para>
  </refsect1>
@@ -28,18 +28,18 @@
   <para>
    <variablelist>
     <varlistentry>
-     <term><parameter>left_operand</parameter></term>
+     <term><parameter>base</parameter></term>
      <listitem>
       <para>
-       The left operand, as a string.
+       The base, as an integral string (i.e. the scale has to be zero).
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
-     <term><parameter>right_operand</parameter></term>
+     <term><parameter>exponent</parameter></term>
      <listitem>
       <para>
-       The right operand, as a string.
+       The exponent, as an non-negative, integral string (i.e. the scale has to be zero).
       </para>
      </listitem>
     </varlistentry>
@@ -47,7 +47,7 @@
      <term><parameter>modulus</parameter></term>
      <listitem>
       <para>
-       The modulus, as a string.
+       The modulus, as an integral string (i.e. the scale has to be zero).
       </para>
      </listitem>
     </varlistentry>
@@ -60,7 +60,7 @@
   &reftitle.returnvalues;
   <para>
    Returns the result as a string, or &null; if <parameter>modulus</parameter>
-   is 0.
+   is <literal>0</literal> or <parameter>exponent</parameter> is negative.
   </para>
  </refsect1>