perlapi.pod: remove AvARRAY() example from sortsv()

The docs for the Perl_sort() API function include a 1-line example
of sorting an AV in-place using  AvARRAY(av). Since AvARRAY() isn't
part of the API and the example would fail on tied or magic arrays,
just delete it.

At the same time, clarify the docs a bit for Perl_sort() and
Perl_sort_flags()

diff --git a/pp_sort.c b/pp_sort.c
index 4ffe224..21e4574 100644 (file)
--- a/pp_sort.c
+++ b/pp_sort.c
@@ -1428,9 +1428,7 @@ S_qsortsv(pTHX_ gptr *list1, size_t nmemb, SVCOMPARE_t cmp, U32 flags)
 
 =for apidoc sortsv
 
-Sort an array.  Here is an example:
-
-    sortsv(AvARRAY(av), av_top_index(av)+1, Perl_sv_cmp_locale);
+In-place sort an array of SV pointers with the given comparison routine.
 
 Currently this always uses mergesort.  See C<L</sortsv_flags>> for a more
 flexible routine.
@@ -1449,7 +1447,8 @@ Perl_sortsv(pTHX_ SV **array, size_t nmemb, SVCOMPARE_t cmp)
 /*
 =for apidoc sortsv_flags
 
-Sort an array, with various options.
+In-place sort an array of SV pointers with the given comparison routine,
+with various SORTf_* flag options.
 
 =cut
 */