add support for __array_prepare__

1 files changed, 23 insertions, 8 deletions

diff --git a/doc/source/reference/arrays.classes.rst b/doc/source/reference/arrays.classes.rst
index 671c95bbf..f9abfbafa 100644
--- a/doc/source/reference/arrays.classes.rst
+++ b/doc/source/reference/arrays.classes.rst
@@ -47,14 +47,29 @@ customize:
    update meta-information from the "parent." Subclasses inherit a
    default implementation of this method that does nothing.
 
-.. function:: __array_wrap__(array)
-
-   This method should return an instance of the subclass from the
-   :class:`ndarray` object passed in. For example, this is called
-   after every :ref:`ufunc <ufuncs.output-type>` for the object with
-   the highest array priority. The ufunc-computed array object is
-   passed in and whatever is returned is passed to the
-   user. Subclasses inherit a default implementation of this method.
+.. function:: __array_prepare__(array, context=None)
+
+   At the beginning of every :ref:`ufunc <ufuncs.output-type>`, this
+   method is called on the input object with the highest array
+   priority, or the output object if one was specified. The output
+   array is passed in and whatever is returned is passed to the ufunc.
+   Subclasses inherit a default implementation of this method which
+   simply returns the output array unmodified. Subclasses may opt to
+   use this method to transform the output array into an instance of
+   the subclass and update metadata before returning the array to the
+   ufunc for computation.
+
+.. function:: __array_wrap__(array, context=None)
+
+   At the end of every :ref:`ufunc <ufuncs.output-type>`, this method
+   is called on the input object with the highest array priority, or
+   the output object if one was specified. The ufunc-computed array
+   is passed in and whatever is returned is passed to the user.
+   Subclasses inherit a default implementation of this method, which
+   transforms the array into a new instance of the object's class. Subclasses
+   may opt to use this method to transform the output array into an
+   instance of the subclass and update metadata before returning the
+   array to the user.
 
 .. data:: __array_priority__