[m-rev.] for review: structured representation of option documentation

[Julien Fischer]

Another thought on this ...

On Fri, 23 May 2025 at 23:22, Zoltan Somogyi <zoltan.somogyi at runbox.com> wrote:

> diff --git a/compiler/options.m b/compiler/options.m
> index 234b29dab..b1a64c67b 100644
> --- a/compiler/options.m
> +++ b/compiler/options.m

...

> +:- type help
> +    --->    gen_help(


This type should contain a field that gives a link (e.g. a field gh_option) to
the relevant member of the option/0 type. That way the usage message processor
could look up details of the option, like its default value, using the usual
predicates. (Doing this will also make it more likely that the documentation
is updated if the option is changed or deleted.)

> +                % The name of the option.
> +                gh_long_name            :: string,
> +
> +                % Any alternate names of the option.
> +                % We have many options that have both British and American
> +                % spelling of the option name, and some have both
> +                % short and long versions.
> +                gh_alt_long_names       :: list(string),
> +
> +                % Every character in this field is a short name of the option.
> +                gh_short_names          :: list(char),
> +
> +                % If the option takes an argument, then this should contain
> +                % the name of the placeholder for that argument.
> +                gh_maybe_arg            :: maybe_opt_arg,
> +
> +                % Is the option's documentation printed for users, or not?
> +                gh_public_or_private    :: help_public_or_private,
> +
> +                % The lines describing the effect of the option.
> +                gh_description          :: list(string)
> +            )

Julien.