[m-dev.] diff: improvements to documentation of C interface

[Fergus Henderson]

Peter Schachte, you wrote:
> > +   If there is a `pragma c_code' declaration for a mode of a predicate
> > +or function, then that mode of the predicate may not have determinism
> > +`multi' or `nondet', there must not be any clauses for that predicate
> > +or function, and there must be a `pragma c_code' goal for every mode of
> > +the predicate or function.
> 
> Is `goal' the right word for this?  Wouldn't `declaration' or `directive' be
> more accurate?

Good point.

> > +   `SUCCESS_INDICATOR' should not be used other than as the target of
> > +an assignment.  (For example, it may be `#define'd to a register, so
> > +you should not try to take its address.) Procedures whose determinism
> >  indicates that that they cannot fail should not access
> > +`SUCCESS_INDICATOR'.
> 
> Can `SUCCESS_INDICATOR' be used as an rvalue?

The language reference manual passage quoted above forbids it.
But yes, it would work under the current implementation.

> For example, would
> 
> 	SUCCESS_INDICATOR = check_something();
> 	do_something();
> 	SUCCESS_INDICATOR = SUCCESS_INDICATOR && check_something_else();
> 
> be allowed?  Or
> 
> 	SUCCESS_INDICATOR = TRUE;
> 	while (SUCCESS_INDICATOR && i<j) {
> 	    ... SUCCESS_INDICATOR = ...
> 	}
> 
> These sorts of things could be convenient.

Well, it's easy enough to use

	{
	  bool succeeded = check_something();
	  do_something();
	  SUCCESS_INDICATOR = succeeded && check_something_else();
	}

or

 	{
	  bool succeeded = TRUE;
 	  while (succeeded && i<j) {
 	      ... succeeded = ...
	  }
	  SUCCESS_INDICATOR = succeeded;
 	}

I don't see much value in changing the existing wording.

-- 
Fergus Henderson <fjh at cs.mu.oz.au>   |  "I have always known that the pursuit
WWW: <http://www.cs.mu.oz.au/~fjh>   |  of excellence is a lethal habit"
PGP: finger fjh at 128.250.37.3         |     -- the last words of T. S. Garp.