[m-dev.] For review: documentation for solver types

[Ralph Becket]

Peter Moulder, Sunday,  1 August 2004:
> On Thu, Jul 22, 2004 at 05:11:56PM +1000, Ralph Becket wrote:
> > + at node The any inst
> > + at subsection The any inst
> 
> Suggest "The `any' inst", at least for the subsection.

Done.

> > +More formally, @samp{X} is ground if for any values @samp{Y} and
> > + at samp{Z} that unify with @samp{X}, it is the case that @samp{Y} and
> > + at samp{Z} also unify with each other.
> 
> `any' is a danger word in definitions: it can mean either forall or
> exists.  I initially read it as exists in the above.  Please change `any
> values' to `each pair of values' or `all values'.

Done.

> 
> > + at end example
> > +
> > +declare types @samp{t1/0} and @samp{t2/2} to be abstract solver types.
> 
> Please add `@noindent' on a line by itself before `declare'.

Done.

> 
> > + at samp{solver_type} values may be represented by
> > +ground at samp{representation_type} values (in the context of the
> 
> Presumably add a space before `ground' and `@samp{rep...}'.
> 
> Btw, I believe @samp{...} adds single quotes around the `...'.  I don't
> think this necessary for most uses of solver_type; @code{...} would
> suffice.  E.g. I think "@samp{free} @samp{solver_type} variable" will
> look strange with all the quotation.

Done.

> 
> > +Calls to this predicate are inserted automatically by the compiler when
> > +a @samp{free} @samp{solver_type} variable has to be converted to @samp{any}
> > +(the initialisation predicate is responsible for registering the new,
> > +unbound variable with the corresponding constraint solver state).
> 
> Use a separate sentence for this parenthesis:
> 
>  {any}.  (The ... state.)

Done.

> 
> > +Under the current design the compiler does not have enough information
> 
> Easier to parse with a comma after "design".

Done.

> 
> > +We intend to lift this
> > +restriction with an extension to the current design in the future.
> 
> `in the future' is redundant.  (If you disagree, please at least move it
> to just after "lift this restriction" rather than let people spend time
> exploring the parse possibility "the current design in the future".)

Done.

Thanks for the feedback!
-- Ralph
--------------------------------------------------------------------------
mercury-developers mailing list
Post messages to:       mercury-developers at cs.mu.oz.au
Administrative Queries: owner-mercury-developers at cs.mu.oz.au
Subscriptions:          mercury-developers-request at cs.mu.oz.au
--------------------------------------------------------------------------