# HG changeset patch
# User Rik <rik@octave.org>
# Date 1462396307 25200
# Node ID e47eb34f1b05d23014f698c6645f32961475d30d
# Parent  32a6d948fea7d60565c8f5043d5441e830444a91
sortrows.m: Improve docstring (bug #47844).

* sortrows.m: Clarify that lexicographical sort is only applied to string
elements.  Add an example of how to use function.

diff -r 32a6d948fea7 -r e47eb34f1b05 scripts/general/sortrows.m
--- a/scripts/general/sortrows.m	Tue May 03 09:58:27 2016 -0700
+++ b/scripts/general/sortrows.m	Wed May 04 14:11:47 2016 -0700
@@ -23,9 +23,25 @@
 ## Sort the rows of the matrix @var{A} according to the order of the columns
 ## specified in @var{c}.
 ##
-## If @var{c} is omitted, a lexicographical sort is used.  By default ascending
-## order is used however if elements of @var{c} are negative then the
-## corresponding column is sorted in descending order.
+## By default (@var{c} omitted, or a particular column unspecified in @var{c})
+## an ascending sort order is used.  However, if elements of @var{c} are
+## negative then the corresponding column is sorted in descending order.  If
+## the elements of @var{A} are strings then a lexicographical sort is used.
+##
+## Example: sort by column 2 in descending order, then 3 in ascending order
+##
+## @example
+## @group
+## x = [ 7, 1, 4;
+##       8, 3, 5;
+##       9, 3, 6 ];
+## sortrows (x, [-2, 3])
+##    @result{} 8  3  5
+##       9  3  6
+##       7  1  4
+## @end group
+## @end example
+##
 ## @seealso{sort}
 ## @end deftypefn