[m-rev.] diff: foreign interface documentation fixes

[Fergus Henderson]

On 25-Jul-2001, Tyson Dowd <trd at cs.mu.OZ.AU> wrote:
> On 25-Jul-2001, Fergus Henderson <fjh at cs.mu.OZ.AU> wrote:
> > On 24-Jul-2001, Tyson Dowd <trd at cs.mu.OZ.AU> wrote:
> > > 
> > > > +Entities declared in @samp{pragma foreign_decl} declarations should be
> > > > +visible in @samp{pragma foreign_code} and @samp{pragma foreign_proc}
> > > > +declarations that specify the same foreign language and occur in in the
> > > > +same Mercury module.
> > > 
> > > *should* be visible?  I'm not sure why you qualify it like that.
> > 
> > Well, this is somewhat language-specific; it's not entirely clear what
> > it means for an entity to be "visible" in an arbitrary language.
> > This requirement is not easily formally specifiable, without specifying
> > the language in question. 
> > 
> > Hence I think the word "should" is appropriate.  It's more along the lines of
> > what would belongs in a "Recommended Practice" (C99) or "Implementation Advice"
> > (Ada95) section of a language standard, rather than a formally specified
> > requirement for which there is no doubt about exactly what it means.
> 
> Ok, that's a good idea, but we should mark this paragraph in some way to
> indicate it is advice to the implementor.

Well, maybe; the use of the word "should" in the phrase "should be" (rather
than "must be", "shall be", or just "is") already indicates that this is not
a strict requirement.  We should try to be clear, but I don't think we need
to aim for a completely standardese level of precision at this point.

> And say that the user should consult the user guide for specific information.  

The specific information for individual languages should go in the
reference manual.

-- 
Fergus Henderson <fjh at cs.mu.oz.au>  |  "I have always known that the pursuit
The University of Melbourne         |  of excellence is a lethal habit"
WWW: <http://www.cs.mu.oz.au/~fjh>  |     -- the last words of T. S. Garp.
--------------------------------------------------------------------------
mercury-reviews mailing list
post:  mercury-reviews at cs.mu.oz.au
administrative address: owner-mercury-reviews at cs.mu.oz.au
unsubscribe: Address: mercury-reviews-request at cs.mu.oz.au Message: unsubscribe
subscribe:   Address: mercury-reviews-request at cs.mu.oz.au Message: subscribe
--------------------------------------------------------------------------