# HG changeset patch
# User Rik <rik@octave.org>
# Date 1486011997 28800
# Node ID be2654b2f34f1966305f4ffb8a29ac5c1089f274
# Parent  03736526b6d81986cae190357afe1d47b61af5eb# Parent  01bf5c733de7f63c9b4771bb2674a94ca67ce0ff
maint: merge stable to default.

diff -r 03736526b6d8 -r be2654b2f34f scripts/miscellaneous/cast.m
--- a/scripts/miscellaneous/cast.m	Wed Feb 01 20:41:45 2017 -0800
+++ b/scripts/miscellaneous/cast.m	Wed Feb 01 21:06:37 2017 -0800
@@ -20,7 +20,8 @@
 ## @deftypefn {} {} cast (@var{val}, "@var{type}")
 ## Convert @var{val} to data type @var{type}.
 ##
-## @var{val} must be one of the numeric classes:
+## Both @var{val} and @var{type} are typically one of the following built-in
+## classes:
 ##
 ## @example
 ## @group
@@ -52,6 +53,18 @@
 ## @end group
 ## @end example
 ##
+## Programming Note: This function relies on the object @var{val} having a
+## conversion method named @var{type}.  User-defined classes may implement only
+## a subset of the full list of types shown above.  In that case, it may be
+## necessary to call cast twice in order to reach the desired type.
+## For example, the conversion to double is nearly always implemented, but
+## the conversion to uint8 might not be.  In that case, the following code will
+## work
+##
+## @example
+## cast (cast (@var{user_defined_val}, "double"), "uint8")
+## @end example
+##
 ## @seealso{typecast, int8, uint8, int16, uint16, int32, uint32, int64, uint64, double, single, logical, char, class, typeinfo}
 ## @end deftypefn