[m-rev.] for post-commit review: better diagnostic for missing higher order insts

[Peter Wang]

On Wed, 26 Jul 2023 20:01:08 +1000 "Zoltan Somogyi" <zoltan.somogyi at runbox.com> wrote:
> 
> > diff --git a/doc/reference_manual.texi b/doc/reference_manual.texi
> > index fb00efe00..d14c4ee3e 100644
> > --- a/doc/reference_manual.texi
> > +++ b/doc/reference_manual.texi
> 
> > + at footnote{If all instances of a given type are expected to use
> > +a single inst or a single mode,
> > +there is a convention where programmers will give that inst or mode
> > +the same name as the type.
> > +This works because types, insts and modes belong to separate namespaces
> > +so the names do not conflict.
> 
> I would add a comma after namespaces.
> 

Done.

> > +Nonetheless, there is usually no need to define a named mode.
> > +It is clearer to write a mode using @samp{in()} or @samp{out()}
> > +around a named inst.}
> >  
> >  The general form of higher order insts follows one of two patterns,
> >  one for predicates, and one for functions.
> > @@ -6344,6 +6310,34 @@ around any instances of these patterns in Mercury code.
> >  @c modes include higher order insts/modes, which would be too complex to
> >  @c be useful as an example to novices.
> >  
> > +As a convenience,
> > +the language allows you to write a higher order @emph{mode}
> > +using the same syntax as a higher order @emph{inst}.
> > +If @var{HOInst} has the form of a higher order inst,
> > +then writing @var{HOInst} where a mode is required
> > +is the same as writing @samp{in(HOInst)},
> > +which is in turn equivalent to @samp{HOInst >> HOInst}.
> > +Therefore,
> > +you can omit @samp{in()} around the higher order inst of an input argument.
> > +For example,
> > +
> > + at example
> > +:- mode foldl(in(pred(in, in, out) is det), in, in, out) is det.
> > + at end example
> > +
> > + at noindent
> > +can also be written as
> > +
> > + at example
> > +:- mode foldl(pred(in, in, out) is det, in, in, out) is det.
> > + at end example
> 
> I think the footnote should be moved here, since
> it talks about this construct.

I left the footnote directly after the example showing how you give
names to higher order insts and modes. The footnote explains why the
names do not conflict, and recommends against defining new modes.

After the example of using higher order mode syntax, we could add a
slight recommendation against it, e.g.

    For example,

        :- mode foldl(in(pred(in, in, out) is det), in, in, out) is det.

    can also be written as

        :- mode foldl(pred(in, in, out) is det, in, in, out) is det.

    but the former may be easier to understand.

Peter