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

[Mark Brown]

On Mon, Oct 31, 2022 at 1:44 PM Zoltan Somogyi
<zoltan.somogyi at runbox.com> wrote:
>
>
>
> 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.

Done.

>
> > -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, /

Done.

>
> >  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.

We do say this elsewhere in the Operators section, but even then I get
confused every time and need to check. So I would agree with the
latter change, though we might want to allow more room for lower
precedence operators to be added in the future.

>
> 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/

Done.

>
> > +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 ...".

We already define "operator term" so I think that works, but I've
added a parenthetical reminder of the definition here.

>
> > +Sub-modules may be recursively qualified,
> > +e.g.@: @samp{module.submodule.name(Args)}.
>
> I don't think this gets your point across.

Changed to:
+The module name used in a module qualified term
+may itself be module qualified if it is a sub-module,
+e.g.@: @samp{module.submodule.name(Args)}.

I've also added a definition for "fully qualified" here, as we use this later.

>
> > +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."

Done.

I've also moved this point after the description of 'use_module',
since the module qualification requirements depend on this definition.
Perhaps you could take a look at the additional changes? Diff and
relative diff are attached (not sure which is easiest).

Thanks for the review,
Mark

>
> The diff is otherwise fine.
>
> Zoltan.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: diff
Type: application/octet-stream
Size: 5311 bytes
Desc: not available
URL: <http://lists.mercurylang.org/archives/reviews/attachments/20221031/b501e8c1/attachment-0002.obj>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: reldiff
Type: application/octet-stream
Size: 4204 bytes
Desc: not available
URL: <http://lists.mercurylang.org/archives/reviews/attachments/20221031/b501e8c1/attachment-0003.obj>