[m-rev.] for post-commit review: improve some comments in the library

[Julien Fischer]

On Sat, 24 Jan 2026 at 01:19, Zoltan Somogyi <zoltan.somogyi at runbox.com> wrote:

> Improve the documentation of some library modules.
>
> library/assoc_list.m:
> library/deconstruct.m:
> library/integer.m:
> library/io.m:
> library/store.m:
> library/string.m:
> library/thread.channel.m:
> library/type_desc.m:
> library/varset.m:
>     As above.

...

> diff --git a/library/deconstruct.m b/library/deconstruct.m
> index cdb0cae2d..a4693dff7 100644
> --- a/library/deconstruct.m
> +++ b/library/deconstruct.m

...

> @@ -177,32 +199,39 @@
>      --->    some [T] arg(T)
>      ;       no_arg.
>
> -    % arg_cc/3 is similar to arg/4, except that it handles arguments with
> -    % non-canonical types. The possible non-existence of an argument is
> -    % encoded using a maybe type.
> +    % arg_cc(Data, Index, Argument):
> +    %
> +    % Does the same job as arg/4, except
> +    %
> +    % - it assumes include_details_cc as the noncanon_handling argument,
> +    %   meaning it can handle arguments with non-canonical types;
> +    % - it returns `no_arg' instead of failing; and
> +    % - it wraps `arg()' around the returned argument on success.
>      %
>  :- pred arg_cc(T::in, int::in, maybe_arg::out) is cc_multi.
>
> -    % named_arg(Data, NonCanon, Name, Argument)
> +    % named_arg(Data, NonCanon, Name, Argument):
>      %
> -    % Same as arg/4, except the chosen argument is specified by giving
> -    % its name rather than its position. If Data has no argument with that
> -    % name, named_arg fails.
> +    % Does the same job as as arg/4, but with the chosen argument

Double "as".

> +    % being specified by giving its name rather than its position.
> +    % If Data has no argument with the given name, named_arg fails.

Just:

     Fails if Data has no argument with the given name.

(Which is the form used below.)

...

> diff --git a/library/io.m b/library/io.m
> index 588fc6706..dc1a95827 100644
> --- a/library/io.m
> +++ b/library/io.m
> @@ -1073,23 +1073,30 @@
>      % its first argument. In all cases, the argument to output can be of any
>      % type. It is output in a format that is intended to be human readable.
>      %
> -    % If the argument is just a single string or character, it will be printed
> -    % out exactly as is (unquoted). If the argument is of type integer (i.e.
> -    % an arbitrary precision integer), then its decimal representation will be
> -    % printed. If the argument is of type univ, then the value stored in the
> -    % univ will be printed out, but not the type. If the argument is of
> -    % type date_time, it will be printed out in the same form as the string
> -    % returned by the function date_to_string/1. If the argument is of type
> -    % duration, it will be printed out in the same form as the string
> -    % returned by the function duration_to_string/1.
> +    % - If the argument is just a single string or character,
> +    %   it will be printed out exactly as is (unquoted).

add "then".

> +    %
> +    % - If the argument is of type integer (i.e. it is an arbitrary precision
> +    %   integer), then its decimal representation will be printed.
> +    %
> +    % - If the argument is of type univ, then the value stored in the univ
> +    %   will be printed out, but not the type.
> +    %
> +    % - If the argument is of type date_time, it will be printed out
> +    %   in the same form as the string returned by the date_to_string/1
> +    %   function.

Ditto.

> +    %
> +    % - If the argument is of type duration, it will be printed out
> +    %   in the same form as the string returned by the duration_to_string/1
> +    %   function.

Ditto.

That looks fine otherwise.

Julien.