[m-rev.] for post-commit review: improve comments in list.m

[Julien Fischer]

On Thu, 23 Dec 2021, Zoltan Somogyi wrote:

> This started as a way of addressing issues discussed recently
> on m-users, but I found many other places that needed improvement.
>
> For review by anyone.

> diff --git a/library/list.m b/library/list.m
> index b756ab21f..e4b8f9622 100644
> --- a/library/list.m
> +++ b/library/list.m
> 
> ...
> 
> @@ -300,64 +306,78 @@
> 
> ...
> 
> -    % delete_all(List0, Elem) = List is true iff List is List0 with
> -    % all occurrences of Elem removed.
> +    % delete_all(List0, Elem) = List:
> +    %
> +    % True iff List is List0 with all occurrences of Elem removed.
>      %
>  :- func delete_all(list(T), T) = list(T).
>  :- pred delete_all(list(T), T, list(T)).
>  :- mode delete_all(di, in, uo) is det.
>  :- mode delete_all(in, in, out) is det.
> 
> -    % delete_nth(List0, N, List) is true iff List0 has an Nth element,
> +    % delete_nth(List0, N, List):
> +    %
> +    % True iff List0 has an Nth element,

s/Nth/N'th/

>      % and List is List0 with this element deleted.
>      %
>  :- pred delete_nth(list(T)::in, int::in, list(T)::out) is semidet.

...

> @@ -1859,11 +1959,17 @@
>
>  %---------------------%
> 
> -    % map_foldr(Pred, InList, OutList, Start, End) calls Pred
> -    % with an accumulator (with the initial value of Start) on
> -    % each element of InList (working right-to-left) to transform
> -    % InList into OutList. The final value of the accumulator is
> -    % returned in End.
> +    % map_foldr(Pred, InList, OutList, Start, End):
> +    %
> +    % Calls Pred on each element of InList, working left-to-right.

s/left-to-right/right-to-left/

> +    % The second argument of that call will be included in OutList,
> +    % while the third and fourth will represent respectively
> +    % the current and the next value of a piece of state.
> +    % (Such current-next argument pairs are usually called an accumulator,
> +    % because the usual use case is that the successive calls to Pred
> +    % accumulate pieces of information.) The initial value of the accumulator
> +    % is Start, each call to Pred updates it to the next value, and
> +    % foldl returns its final value as End.
>      %
>  :- pred map_foldr(pred(L, M, A, A), list(L), list(M), A, A).
>  :- mode map_foldr(pred(in, out, in, out) is det, in, out, in, out)

That's fine otherwise.

Julien.