Fix #69182: imagecropauto function not properly documented

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

reference/image/functions/imagecropauto.xml

@@ -17,11 +17,9 @@
    <methodparam choice="opt"><type>int</type><parameter>color</parameter><initializer>-1</initializer></methodparam>
   </methodsynopsis>
   <para>
-
+   Automatically crops an image according to the given
+   <parameter>mode</parameter>.
   </para>
-
-  &warn.undocumented.func;
-
  </refsect1>
 
  <refsect1 role="parameters">
@@ -32,15 +30,73 @@
     <term><parameter>mode</parameter></term>
     <listitem>
      <para>
-      One of <constant>IMG_CROP_*</constant> constants.
+      One of the following constants:
      </para>
+     <variablelist>
+      <varlistentry>
+       <term><constant>IMG_CROP_DEFAULT</constant></term>
+       <listitem>
+        <simpara>
+         Attempts to use <constant>IMG_CROP_TRANSPARENT</constant> and if it
+         fails it falls back to <constant>IMG_CROP_SIDES</constant>.
+        </simpara>
+       </listitem>
+      </varlistentry>
+      <varlistentry>
+       <term><constant>IMG_CROP_TRANSPARENT</constant></term>
+       <listitem>
+        <simpara>
+         Crops out a transparent background.
+        </simpara>
+       </listitem>
+      </varlistentry>
+      <varlistentry>
+       <term><constant>IMG_CROP_BLACK</constant></term>
+       <listitem>
+        <simpara>
+         Crops out a black background.
+        </simpara>
+       </listitem>
+      </varlistentry>
+      <varlistentry>
+       <term><constant>IMG_CROP_WHITE</constant></term>
+       <listitem>
+        <simpara>
+          Crops out a white background.
+        </simpara>
+       </listitem>
+      </varlistentry>
+      <varlistentry>
+       <term><constant>IMG_CROP_SIDES</constant></term>
+       <listitem>
+        <simpara>
+         Uses the 4 corners of the image to attempt to detect the background to
+         crop.
+        </simpara>
+       </listitem>
+      </varlistentry>
+      <varlistentry>
+       <term><constant>IMG_CROP_THRESHOLD</constant></term>
+       <listitem>
+        <simpara>
+         Crops an image using the given <parameter>threshold</parameter> and
+         <parameter>color</parameter>.
+        </simpara>
+       </listitem>
+      </varlistentry>
+     </variablelist>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>threshold</parameter></term>
     <listitem>
      <para>
-      Used in <constant>IMG_CROP_THRESHOLD</constant> mode.
+      Specifies the tolerance in percent to be used while comparing the image
+      color and the color to crop. The method used to calculate the color
+      difference is based on the color distance in the RGB(a) cube.
+     </para>
+     <para>
+      Used only in <constant>IMG_CROP_THRESHOLD</constant> mode.
      </para>
     </listitem>
    </varlistentry>
@@ -48,7 +104,10 @@
     <term><parameter>color</parameter></term>
     <listitem>
      <para>
-      Used in <constant>IMG_CROP_THRESHOLD</constant> mode.
+      Either an RGB color value or a palette index.
+     </para>
+     <para>
+      Used only in <constant>IMG_CROP_THRESHOLD</constant> mode.
      </para>
     </listitem>
    </varlistentry>
@@ -58,10 +117,39 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-   Return cropped image resource on success&return.falseforfailure;.
+   Returns a cropped image resource on success&return.falseforfailure;.
+   If no cropping would occur, or the complete image would be cropped, that is
+   treated as failure, i.e. <function>imagecrop</function> returns &false;.
   </para>
  </refsect1>
 
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <para>
+   <example>
+    <title>Proper handling of auto-cropping</title>
+    <para>
+     As noted in the return value section, <function>imagecropauto</function>
+     returns &false; when there is either nothing to crop or the whole image
+     would be cropped. In this example we have an image resource
+     <literal>$im</literal> which should be automatically cropped only if there
+     is something to crop; otherwise we want to proceed with the original image.
+    </para>
+    <programlisting role="php">
+<![CDATA[
+<?php
+$cropped = imagecropauto($im, IMG_CROP_DEFAULT);
+if ($cropped !== false) { // in case a new image resource was returned
+    imagedestroy($im);    // we destroy the original image
+    $im = $cropped;       // and assign the cropped image to $im
+}
+?>
+]]>
+    </programlisting>
+   </example>
+  </para>
+ </refsect1>
+ 
 </refentry>
 
 <!-- Keep this comment at the end of the file