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

[Fergus Henderson]

On 31-Oct-2002, Peter Ross <pro at missioncriticalit.com> wrote:
> On Thu, Oct 31, 2002 at 10:38:42PM +1100, Fergus Henderson wrote:
> > On 31-Oct-2002, Peter Ross <pro at missioncriticalit.com> wrote:
> > > 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"?
>
> It is brittle in the sense that both Tyson and I hate using it.  Things
> go wrong all the time

More often than for the C# or IL interfaces?  Why?

> and when they do the error message you get out of
> the MC++ compiler is quite often incomprehensible.

So the language reference manual should recommend against using the MC++
interface because MSVC gives poor error messages?

I don't know, to me that just doesn't seem like an appropriate thing to
put in the Mercury language reference manual.

> > 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.
>
> I do think a piece of advice along the lines of: this can be the most
> difficult interface of the three interfaces to use, so only use it if
> you really need to.

AFAIK it shouldn't be any harder to use than the C# or IL interfaces,
except in that MC++ might be a more complicated language and/or might
have a worse compiler.  But those are the usual issues when choosing a
language.  I think people reading the Mercury language reference manual
should be capable of making reasonable decisions about which of the
three languages is appropriate for a given task without needing such
advice.

Here's the relative diff to address your other comment.

--- reference_manual.texi.old	Fri Nov  1 00:02:56 2002
+++ reference_manual.texi	Fri Nov  1 00:02:58 2002
@@ -5442,8 +5442,10 @@
 For output arguments,
 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}.
+argument of type @samp{int} would map to a C# @samp{ref int}
+function parameter.  (Note that we map to @samp{ref int}, not @samp{out int};
+for procedures that can fail, output arguments only need to be set if the
+procedure succeeds.)
 If the Mercury procedure can fail,
 then its IL or C# function should return a truth value of type
 @samp{bool} (i.e.@: @samp{System.Bool}) indicating success or failure:
-- 
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
--------------------------------------------------------------------------