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

[Peter Schachte]

On Fri, 19 Sep 1997, Fergus Henderson wrote:

> This change is in response to a suggestion by Peter Schachte.
> 
> doc/reference_manual.texi:
> 	Improve the documentation of the C interface:
> 	show how to use `pragma c_code' to define functions,
> 	and also make a few other minor improvements.

Thank you, this looks good.  A few comments:

> +   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?

> -   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
> +   `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.
> +`SUCCESS_INDICATOR'.

Can `SUCCESS_INDICATOR' be used as an rvalue?  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.


-Peter Schachte      URL:  http://www.cs.mu.oz.au/~pets/
pets at cs.mu.OZ.AU     PGP:  finger pets at 128.250.37.150 for key
    Do insects spend hours demammaling their programs?