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

[Peter Ross]

On Wed, Oct 30, 2002 at 03:50:30AM +1100, Fergus Henderson wrote:
> I've probably screwed something up here, so I'd really appreciate it if
> people -- especially Tyson and Peter Ross, but the more, the merrier --
> could review this.
> 
> Branches: main
> Estimated hours taken: 5
> 
> Clean up the documentation for the foreign language interface.
> 
> doc/reference_manual.texi:
> 	Document the C# and MC++ interfaces.
> 	Update the documentation for the foreign language interface
> 	chapter to remove much of the stuff about it not being supported,
> 	and to instead say that this interface is now the preferred one
> 	to use for new code.
> 	Also, fix a few Texinfo formatting errors.
> 
> Workspace: /mnt/ceres/home/ceres/fjh/mercury
> Index: doc/reference_manual.texi
> ===================================================================
> RCS file: /home/mercury1/repository/mercury/doc/reference_manual.texi,v
> retrieving revision 1.259
> diff -u -d -r1.259 reference_manual.texi
> --- 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.

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

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

Otherwise that looks good, thanks Fergus.
--------------------------------------------------------------------------
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
--------------------------------------------------------------------------