Note the fix for bug #65171, and generally flesh out the imagescale() docs.

Fixes doc bug #68239 (Incorrect documentation or library bug).


git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@335164 c90b9560-bf6c-de11-be94-00142212c4b1

reference/image/functions/imagescale.xml

@@ -17,11 +17,9 @@
    <methodparam choice="opt"><type>int</type><parameter>mode</parameter><initializer>IMG_BILINEAR_FIXED</initializer></methodparam>
   </methodsynopsis>
   <para>
-
+   <function>imagescale</function> scales an image using the given
+   interpolation algorithm.
   </para>
-
-  &warn.undocumented.func;
-
  </refsect1>
 
  <refsect1 role="parameters">
@@ -32,7 +30,7 @@
     <term><parameter>new_width</parameter></term>
     <listitem>
      <para>
-      
+      The width to scale the image to.
      </para>
     </listitem>
    </varlistentry>
@@ -40,8 +38,15 @@
     <term><parameter>new_height</parameter></term>
     <listitem>
      <para>
-      
+      The height to scale the image to. If omitted or negative, the aspect
+      ratio will be preserved.
      </para>
+     <caution>
+      <para>
+       You should always provide the height if using PHP 5.5.18 or earlier, or
+       PHP 5.6.2 or earlier, as the aspect ratio calculation was incorrect.
+      </para>
+     </caution>
     </listitem>
    </varlistentry>
    <varlistentry>
@@ -62,10 +67,35 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-   Return scaled image resource on success&return.falseforfailure;.
+   Return the scaled image resource on success&return.falseforfailure;.
   </para>
  </refsect1>
 
+ <refsect1 role="changelog">
+  &reftitle.changelog;
+  <para>
+   <informaltable>
+    <tgroup cols="2">
+     <thead>
+      <row>
+       <entry>&Version;</entry>
+       <entry>&Description;</entry>
+      </row>
+     </thead>
+     <tbody>
+      <row>
+       <entry>5.5.19/5.6.3</entry>
+       <entry>
+        The calculation of the height if <parameter>new_height</parameter> was
+        negative or omitted was fixed; prior to these versions, the aspect
+        ratio was not maintained correctly.
+       </entry>
+      </row>
+     </tbody>
+    </tgroup>
+   </informaltable>
+  </para>
+ </refsect1>
 </refentry>
 
 <!-- Keep this comment at the end of the file