[m-rev.] for review: update docs for foreign language interface

[Fergus Henderson]

On 31-Oct-2002, Peter Ross <pro at missioncriticalit.com> wrote:
> On Wed, Oct 30, 2002 at 03:50:30AM +1100, Fergus Henderson wrote:
> > --- doc/reference_manual.texi	1 Oct 2002 08:13:26 -0000	1.259
> > +++ doc/reference_manual.texi	29 Oct 2002 16:20:06 -0000
> > @@ -5428,13 +5438,15 @@
> >  terms.
> >  
> >  Mercury arguments declared with input modes are passed by value to the
> > -IL function.
> > +IL or C# function.
> >  For output arguments,
> > -the Mercury implementation will pass to the IL function a reference to
> > -the location in which to store the result. 
> > +the Mercury implementation will pass to the IL or C# function a reference to
> > +the location in which to store the result; for example, a Mercury output
> > +argument of type @samp{int} would map to a C# function parameter with type
> > + at samp{ref int}.
> 
> Maybe it would be good to note that it is 'ref int' not 'out int',
> despite the value being initialised by the callee.

For semidet procedures the value only needs to be initialized by the
callee if the procedure succeeds.

Actually

	argument of type @samp{int} would map to a C# @samp{ref int}
	function parameter.

> >  If the Mercury procedure can fail,
> > -then its IL function should return a truth value of type
> > - at samp{System.Bool} indicating success or failure:
> > +then its IL or C# function should return a truth value of type
> > + at samp{bool} (i.e.@: @samp{System.Bool}) indicating success or failure:
> >  @code{true} indicates success, and @code{false} indicates failure.
> >  If the Mercury procedure is a Mercury function that cannot fail,
> >  and the function result has an output mode,
> 
> > @@ -5600,9 +5612,13 @@
> >  
> >  @item @samp{IL}
> >  Use the string @code{"IL"} to set the foreign language to IL.
> > +IL (sometimes also known as CIL or MSIL) is the Intermediate Language
> > +for the .NET Common Language Runtime.
>
> Isn't the code string "il" not "IL"?

It's case insensitive, actually.

Using "IL" here is consistent with the documentation for the
C interface which says to use "C" rather than "c".
"IL" is the correct name for the language.

> >  @item @samp{Managed C++}
> >  Use the string @code{"MC++"} to set the foreign language to Managed C++.
> > +Managed C++ is C++ with Microsoft's extensions to support interfacing
> > +with and generating code for the .NET Common Language Runtime.
>
> I would a line saying that the MC++ interface is only recommended for
> use when C# or the IL interface can't be used as it is by far the most
> brittle interface.

In what sense is the MC++ interface "brittle"?

I'm not going to advise people to use the IL interface rather than the
MC++ interface, because the MC++ interface is much higher-level than
the IL interface.

I could put in some advice recommending the use of the C# interface in
preference to the MC++ interface on the grounds that it is more portable,
I suppose.

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