Hi Ludo, Alexei,
Please avoid C-speak in documentation if possible.
(See below)
On 22/04/12 00:38, Ludovic Courtès wrote:
> Hi Alexei,
>
> (Removing Cc: guile-devel.)
>
> Thanks for the patch!
>
> Alexei Matveev <alexei.matv...@gmail.com> skribis:
>
>> --- a/libguile/sort.c +++ b/libguile/sort.c @@ -101,9 +101,10 @@
>> SCM_DEFINE (scm_restricted_vector_sort_x,
>> "restricted-vector-sort!", 4, 0, 0, * (not (less? (list-ref list
>> i) (list-ref list (- i 1)))). */ SCM_DEFINE (scm_sorted_p,
>> "sorted?", 2, 0, 0, (SCM items, SCM less), - "Return
>> @code{#t} iff @var{items} is a list or a vector such that\n" -
>> "for all 1 <= i <= m, the predicate @var{less} returns true
>> when\n" - "applied to all elements i - 1 and i") +
>> "Return @code{#t} iff @var{items} is a list or a vector such\n"
>> + "that for all 1 <= i <= m, the predicate @var{less}
>> returns\n" + "@code{#f} when comparing element i to the
>> preceeding element\n" + "i - 1.")
>
> How about this:
>
> Return @code{#t} iff @var{items} is a list or vector such that, for
> each element @var{x} and the next element @var{y} of @var{items},
> @code{(@var{less} @var{x} @var{y})} returns @code{#f}.
>
> This avoids use of ‘m’, which would need to be defined, and makes
> it clear what “comparing element i to the preceeding element”
> means.
>
> What do you think?
>
Please spell out iff, which I presume means "if-and-only-if". The
reason is that on first reading it looks ambiguous to old dinosaurs
like me who may have experience of programming languages using iff as
a token for "if-false" back in the Jurassic period.
Or maybe say:
Return @code{#t} when @var{items} is a list or vector such that,
for each element @var{x} and the next element @var{y} of @var{items},
@code{(@var{less} @var{x} @var{y})} returns @code{#f}.
Cheers,
Ian Hulin
