DOC: Improve the documentation about type promotion

3 files changed, 99 insertions, 13 deletions

diff --git a/doc/source/reference/c-api.array.rst b/doc/source/reference/c-api.array.rst
index 8c2b3a34e..f34176a00 100644
--- a/doc/source/reference/c-api.array.rst
+++ b/doc/source/reference/c-api.array.rst
@@ -958,30 +958,60 @@ Converting data types
     returned when the value will not overflow or be truncated to
     an integer when converting to a smaller type.
 
+    This is almost the same as the result of
+    PyArray_CanCastTypeTo(PyArray_MinScalarType(arr), totype, casting),
+    but it also handles a special case arising because the set
+    of uint values is not a subset of the int values for types with the
+    same number of bits.
+
 .. cfunction:: PyArray_Descr* PyArray_MinScalarType(PyArrayObject* arr)
 
     .. versionadded:: 1.6
 
     If *arr* is an array, returns its data type descriptor, but if
     *arr* is an array scalar (has 0 dimensions), it finds the data type
-    of smallest kind and size to which the value may be converted
+    of smallest size to which the value may be converted
     without overflow or truncation to an integer.
+    
+    This function will not demote complex to float or anything to
+    boolean, but will demote a signed integer to an unsigned integer
+    when the scalar value is positive.
 
 .. cfunction:: PyArray_Descr* PyArray_PromoteTypes(PyArray_Descr* type1, PyArray_Descr* type2)
 
     .. versionadded:: 1.6
 
     Finds the data type of smallest size and kind to which *type1* and
-    *type2* may be safely converted.
+    *type2* may be safely converted. This function is symmetric and
+    associative.
 
 .. cfunction:: PyArray_Descr* PyArray_ResultType(npy_intp narrs, PyArrayObject**arrs, npy_intp ndtypes, PyArray_Descr**dtypes)
 
     .. versionadded:: 1.6
 
-    This applies PyArray_PromoteTypes to all the inputs, along with
+    This applies type promotion to all the inputs,
     using the NumPy rules for combining scalars and arrays, to
     determine the output type of a set of operands.  This is the
-    same result type that ufuncs produce.
+    same result type that ufuncs produce. The specific algorithm
+    used is as follows.
+
+    Categories are determined by first checking which of boolean,
+    integer (int/uint), or floating point (float/complex) the maximum
+    kind of all the arrays and the scalars are.
+    
+    If there are only scalars or the maximum category of the scalars
+    is higher than the maximum category of the arrays,
+    the data types are combined with :cfunc:`PyArray_PromoteTypes`
+    to produce the return value.
+
+    Otherwise, PyArray_MinScalarType is called on each array, and
+    the resulting data types are all combined with
+    :cfunc:`PyArray_PromoteTypes` to produce the return value.
+
+    The set of int values is not a subset of the uint values for types
+    with the same number of bits, something not reflected in
+    :cfunc:`PyArray_MinScalarType`, but handled as a special case in
+    PyArray_ResultType.
 
 .. cfunction:: int PyArray_ObjectType(PyObject* op, int mintype)
 
@@ -2287,6 +2317,9 @@ Array Scalars
 
 .. cfunction:: NPY_SCALARKIND PyArray_ScalarKind(int typenum, PyArrayObject** arr)
 
+    See the function :cfunc:`PyArray_MinScalarType` for an alternative
+    mechanism introduced in NumPy 1.6.0.
+
     Return the kind of scalar represented by *typenum* and the array
     in *\*arr* (if *arr* is not ``NULL`` ). The array is assumed to be
     rank-0 and only used if *typenum* represents a signed integer. If
@@ -2300,6 +2333,9 @@ Array Scalars
 
 .. cfunction:: int PyArray_CanCoerceScalar(char thistype, char neededtype, NPY_SCALARKIND scalar)
 
+    See the function :cfunc:`PyArray_ResultType` for details of
+    NumPy type promotion, updated in NumPy 1.6.0.
+
     Implements the rules for scalar coercion. Scalars are only
     silently coerced from thistype to neededtype if this function
     returns nonzero.  If scalar is :cdata:`NPY_NOSCALAR`, then this
diff --git a/doc/source/reference/ufuncs.rst b/doc/source/reference/ufuncs.rst
index dedbf2929..987a2ec15 100644
--- a/doc/source/reference/ufuncs.rst
+++ b/doc/source/reference/ufuncs.rst
@@ -174,6 +174,13 @@ Casting Rules
 .. index::
    pair: ufunc; casting rules
 
+.. note::
+
+   In NumPy 1.6.0, a type promotion API was created to encapsulate the
+   mechansim for determining output types. See the functions
+   :func:`result_type`, :func:`promote_types`, and
+   :func:`min_scalar_type` for more details.
+
 At the core of every ufunc is a one-dimensional strided loop that
 implements the actual function for a specific type combination. When a
 ufunc is created, it is given a static list of inner loops and a
@@ -267,15 +274,14 @@ types, are interpreted accordingly in ufuncs) without worrying about
 whether the precision of the scalar constant will cause upcasting on
 your large (small precision) array.
 
-
 :class:`ufunc`
 ==============
 
 Optional keyword arguments
 --------------------------
 
-All ufuncs take optional keyword arguments. These represent rather
-advanced usage and will not typically be used by most Numpy users.
+All ufuncs take optional keyword arguments. Most of these represent
+advanced usage and will not typically be used.
 
 .. index::
    pair: ufunc; keyword arguments
diff --git a/numpy/add_newdocs.py b/numpy/add_newdocs.py
index 42e957bb9..a2925eeba 100644
--- a/numpy/add_newdocs.py
+++ b/numpy/add_newdocs.py
@@ -1560,6 +1560,10 @@ add_newdoc('numpy.core.multiarray', 'can_cast',
     out : bool
         True if cast can occur according to the casting rule.
 
+    See also
+    --------
+    dtype, result_type
+
     Examples
     --------
 
@@ -1635,6 +1639,8 @@ add_newdoc('numpy.core.multiarray', 'promote_types',
     kind to which both ``type1`` and ``type2`` may be safely cast.
     The returned data type is always in native byte order.
 
+    This function is symmetric and associative.
+
     Parameters
     ----------
     type1 : dtype or dtype specifier
@@ -1647,10 +1653,13 @@ add_newdoc('numpy.core.multiarray', 'promote_types',
     out : dtype
         The promoted data type.
 
+    Notes
+    -----
+    .. versionadded:: 1.6.0
+
     See Also
     --------
-    issctype, issubsctype, issubdtype, obj2sctype, sctype2char,
-    maximum_sctype, min_scalar_type
+    result_type, dtype, can_cast
 
     Examples
     --------
@@ -1678,7 +1687,7 @@ add_newdoc('numpy.core.multiarray', 'min_scalar_type',
     and smallest scalar kind which can hold its value.  For non-scalar
     array ``a``, returns the vector's dtype unmodified.
 
-    As a special case, floating point values are not demoted to integers,
+    Floating point values are not demoted to integers,
     and complex values are not demoted to floats.
 
     Parameters
@@ -1691,11 +1700,13 @@ add_newdoc('numpy.core.multiarray', 'min_scalar_type',
     out : dtype
         The minimal data type.
 
+    Notes
+    -----
+    .. versionadded:: 1.6.0
 
     See Also
     --------
-    issctype, issubsctype, issubdtype, obj2sctype, sctype2char,
-    maximum_sctype, promote_types
+    result_type, promote_types, dtype, can_cast
 
     Examples
     --------
@@ -1745,6 +1756,33 @@ add_newdoc('numpy.core.multiarray', 'result_type',
     out : dtype
         The result type.
 
+    See also
+    --------
+    dtype, promote_types, min_scalar_type, can_cast
+
+    Notes
+    -----
+    .. versionadded:: 1.6.0
+
+    The specific algorithm used is as follows.
+
+    Categories are determined by first checking which of boolean,
+    integer (int/uint), or floating point (float/complex) the maximum
+    kind of all the arrays and the scalars are.
+    
+    If there are only scalars or the maximum category of the scalars
+    is higher than the maximum category of the arrays,
+    the data types are combined with :func:`promote_types`
+    to produce the return value.
+
+    Otherwise, `min_scalar_type` is called on each array, and
+    the resulting data types are all combined with :func:`promote_types`
+    to produce the return value.
+
+    The set of int values is not a subset of the uint values for types
+    with the same number of bits, something not reflected in
+    :func:`min_scalar_type`, but handled as a special case in `result_type`.
+
     Examples
     --------
     >>> np.result_type(3, np.arange(7, dtype='i1'))
@@ -1911,9 +1949,9 @@ add_newdoc('numpy.core', 'einsum',
           * 'no' means the data types should not be cast at all.
           * 'equiv' means only byte-order changes are allowed.
           * 'safe' means only casts which can preserve values are allowed.
-          * 'unsafe' means any data conversions may be done.
           * 'same_kind' means only safe casts or casts within a kind,
             like float64 to float32, are allowed.
+          * 'unsafe' means any data conversions may be done.
 
     Returns
     -------
@@ -1926,6 +1964,8 @@ add_newdoc('numpy.core', 'einsum',
 
     Notes
     -----
+    .. versionadded:: 1.6.0
+
     The subscripts string is a comma-separated list of subscript labels,
     where each label refers to a dimension of the corresponding operand.
     Repeated subscripts labels in one operand take the diagonal.  For example,
@@ -5496,6 +5536,10 @@ add_newdoc('numpy.core.multiarray', 'dtype',
         Make a new copy of the data-type object. If ``False``, the result
         may just be a reference to a built-in data-type object.
 
+    See also
+    --------
+    result_type
+
     Examples
     --------
     Using array-scalar type: