From 055cdb7c7e4ade095b003dad1ab36a4c5a18b61d Mon Sep 17 00:00:00 2001
From: Christoph Michael Becker <cmb@php.net>
Date: Sun, 9 Oct 2016 11:33:10 +0000
Subject: [PATCH] Document imagecrop()

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@340406 c90b9560-bf6c-de11-be94-00142212c4b1
---
 reference/image/functions/imagecrop.xml     | 40 ++++++++++++++++++---
 reference/image/functions/imagecropauto.xml |  7 ++++
 2 files changed, 42 insertions(+), 5 deletions(-)

diff --git a/reference/image/functions/imagecrop.xml b/reference/image/functions/imagecrop.xml
index ba1734bd6f..6db63fd8ea 100644
--- a/reference/image/functions/imagecrop.xml
+++ b/reference/image/functions/imagecrop.xml
@@ -4,7 +4,7 @@
 <refentry xml:id="function.imagecrop" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
   <refname>imagecrop</refname>
-  <refpurpose>Crop an image using the given coordinates and size, x, y, width and height</refpurpose>
+  <refpurpose>Crop an image to the given rectangle</refpurpose>
  </refnamediv>
 
  <refsect1 role="description">
@@ -15,11 +15,10 @@
    <methodparam><type>array</type><parameter>rect</parameter></methodparam>
   </methodsynopsis>
   <para>
-
+   Crops an image to the given rectangular area and returns the resulting image.
+   The given <parameter>image</parameter> is not modified.
   </para>
 
-  &warn.undocumented.func;
-
  </refsect1>
 
  <refsect1 role="parameters">
@@ -30,7 +29,9 @@
     <term><parameter>rect</parameter></term>
     <listitem>
      <para>
-      Array with keys "x", "y", "width" and "height".
+      The cropping rectangle as <type>array</type> with keys
+      <literal>x</literal>, <literal>y</literal>, <literal>width</literal> and
+      <literal>height</literal>.
      </para>
     </listitem>
    </varlistentry>
@@ -44,6 +45,35 @@
   </para>
  </refsect1>
 
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <example xml:id="function-name.example.basic">
+   <title><function>imagecrop</function> example</title>
+   <para>
+     This example shows how to crop an image to a square area.
+   </para>
+   <programlisting role="php">
+<![CDATA[
+<?php
+$im = imagecreatefrompng('example.png');
+$size = min(imagesx($im), imagesy($im));
+$im2 = imagecrop($im, ['x' => 0, 'y' => 0, 'width' => $size, 'height' => $size]);
+if ($im2 !== FALSE) {
+    imagepng($im2, 'example-cropped.png');
+}
+?>
+]]>
+   </programlisting>
+  </example>
+ </refsect1>
+
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <simplelist>
+   <member><function>imagecropauto</function></member>
+  </simplelist>
+ </refsect1>
+
 </refentry>
 
 <!-- Keep this comment at the end of the file
diff --git a/reference/image/functions/imagecropauto.xml b/reference/image/functions/imagecropauto.xml
index 91c8d49934..15388e3f1d 100644
--- a/reference/image/functions/imagecropauto.xml
+++ b/reference/image/functions/imagecropauto.xml
@@ -150,6 +150,13 @@ if ($cropped !== false) { // in case a new image resource was returned
   </para>
  </refsect1>
  
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <simplelist>
+   <member><function>imagecrop</function></member>
+  </simplelist>
+ </refsect1>
+
 </refentry>
 
 <!-- Keep this comment at the end of the file