[m-rev.] for review: improve module qualifier documentation

[Zoltan Somogyi]

On Mon, 31 Oct 2022 13:28:10 +1100, Mark Brown <mark at mercurylang.org> wrote:
> commit 5a3d921c224204aad24a28a412aa0f776e6a4c30
> Author: Mark Brown <mark at mercurylang.org>
> Date:   Mon Oct 31 13:21:08 2022 +1100
> 
>     improve documentation of module qualifiers

Fix capitalization, add period.

> -Note that operators are a syntactic concept.
> +Operators are a syntactic concept.
>  The @samp{+} infix operator, for example, is only a symbol;
>  it does not mean addition unless you write or import code
>  that defines it as addition.
>  Modules in the Mercury standard library,
>  such as @code{int} and @code{float},
>  provide such arithmetic definitions.
> -To illustrate further,
> +Other non-arithmetic definitions can also be provided,
> +for example,

s/Other/Other, /

>  the @samp{-} infix operator is defined as subtraction by those modules
>  but is defined as a pair constructor by the @code{pair} module.
>  
> @@ -497,6 +498,14 @@ than those with a high ``Priority''.
>  For example, given that
>  @code{+} has priority 500 and @code{*} has priority 400,
>  the term @code{2 * X + Y} is equivalent to @code{(2 * X) + Y}.
> +Note that the module qualification operator, @samp{.},
> +binds more tightly than any other operator.
> +Therefore, operator terms using builtin operators
> +need to be parenthesized in order to be module qualified,
> +for example,
> +integer subtraction can be written as @samp{int.(A - B)}
> +whereas pair construction can be written as @samp{pair.(A - B)}.
> +(@xref{The module system}).

This is fine, but it brings up a point that the manual does not cover,
which is that we don't say that higher numeric priorities bind
*less* tightly than lower numeric priorities.

We can either document this, possibly by saying something
contradictory-looking, such as "higher numeric priority means
lower actual priority", or *fix* it, which we can do by
replacing all current priorities P with max_priority - P.
I prefer the latter, though it would require corresponding changes
to the parser.

Obviusly, such a change would be for a different diff.

> @@ -745,6 +754,9 @@ For example, the principal functor of @samp{foo(bar,baz)} is @samp{foo/2},
>  while the principal functor of @samp{foo} is @samp{foo/0}.
>  The principal functor of a special term is determined
>  @emph{after} term normalization.
> +For module qualfied terms,

s/qualfied/qualified/

> +the principal functor is defined slightly differently
> +(@pxref{The module system}).
>  
>  Note that the word ``functor'' has a number of definitions,
>  but in Mercury it just means
> @@ -6366,17 +6378,30 @@ If the imported entities are only used in the implementation section,
>  the @code{import_module} or @code{use_module} declaration
>  should be in the implementation section.
>  
> -The names of predicates, functions, constructors, constructor fields,
> -types, modes, insts, type classes, and (sub-)modules
> +Functor terms representing
> +predicates, functions, expressions, constructor fields,
> +types, modes, insts, type classes, instances and (sub-)modules
>  can be explicitly module qualified using the @samp{.} operator,
> -e.g.@: @samp{module.name} or @samp{module.submodule.name}.
> -This is useful both for readability and for resolving name conflicts.
> +e.g.@: @samp{module.name} or @samp{module.name(Args)}.
> +Operator terms may also be module qualified with the use of parentheses,
> +e.g.@: @samp{module.(A + B)}.

I would reword this to something like "Functors that are also operators
may also be module qualified, though this requires putting parentheses
around the term they are the principal functor of, such as ...".

> +Sub-modules may be recursively qualified,
> +e.g.@: @samp{module.submodule.name(Args)}.

I don't think this gets your point across.

> +Module qualifiers may be required
> +if overloaded names cannot otherwise be resolved;

I would say "You may need to module qualify a name if that name has
several applicable definitions, and the context of its occurrence
does not resolve this ambiguity."

The diff is otherwise fine.

Zoltan.