[m-rev.] for review: document require_tail_recursion pragmas

[Zoltan Somogyi]

On Wed, 10 Jun 2026 16:59:34 +1000, Julien Fischer <jfischer at opturion.com> wrote:
> > +In declarative languages such as Mercury,
> > +iterations have to implemented by recursive code,
> 
> have to *be*
> 
> That said, since we are only concerned with Mercury here, that
> can be simplified to:
> 
>    In Mercury, iteration must be implemented by recursive code,

I kept the first line, but followed the rest of your text.

> > +The standard technique for avoiding this
> > +is @emph{tail call optimization},
> > +which, when applied to recursive calls, is also called @emph{tail recursion}.
> > +This technique is applicable whenever a call
> > +is the very last thing that a predicate or function does.
> 
> You at least need to say "whenever a *recursive* call" there.
> It can't just be any old call.

No, I did mean tail calls in general, not just tail recursive calls.
This is a visible difference between LLDS and MLDS grades:
LLDS can do any tail call, MLDS can do only tail RECURSIVE calls.
I then forgot to add the paragraph I intended to add about this :-(
I will post this later.

> > +The exception applies to conjunctions that contain two or more recursive calls,
> > +as in the recursive clause of quicksort.
> > +Since obviously only the last of these calls can be a tail call,
> 
> Delete "obviously".

Why?

> > +These ask the compiler to generate a warning
> > +if any recursive call in the body of the named predicate or function,
> > +whether it be self-recursive or mutually recursive,
> > +is not a @emph{tail} call.
> > +It also asks for the warning to be generated
> 
> You swap from plural to singular here and then swap back and forth
> again below.

I switched to singular only.

> > +only in grades that permit tail recursion at all.
> > +(The implementation of some grades,
> > +including grades that permit debugging or perform deep profiling,
> > +need to get control for their own purposes at the end of every clause,
> > +which means that @emph{no} call can be a tail call.)
> > +
> > +(The @samp{pred()} and @samp{func()} wrappers around the name/arity pair
> > +are optional in the usual case where there is no risk of confusion,
> > +but it is good practice to include them anyway.)
> > +
> > +By default, the pragma applies
> > +to all the modes of the specified predicate or function.
> > +If you want it to apply to only a specific subset of those modes,
> > +you can use the first form for a predicate and the second form for a function:
> 
> Examples of the modes specific versions are missing (from above?)

Fixed.

> > + at item in_all_grades
> > +Tell the compiler to generate a diagnostic for non-tail recursion
> > +even in grades that do not allow the possibility of tail recursion.
> > +In such grades, which include debugging and deep profiling grades,
> 
> s/include/includes/
> 
> I suggest emphasising that as well.

If there are any other such grades, I would prefer to list them explicitly.
Do you know any? Does trailing disable tail recursion?

I followed all your other suggestions.

Thanks for the review.

Zoltan.