[m-rev.] for review: new foreign_type syntax

[Fergus Henderson]

On 06-Dec-2001, Tyson Dowd <trd at cs.mu.OZ.AU> wrote:
> Fix and enable the new foreign_type syntax.  We now accept declarations
> such as:
> 
> :- pragma foreign_type(il, xmldoc, "class [System.Xml]System.Xml.XmlDocument").
> Index: doc/reference_manual.texi
...
> @@ -5004,6 +5007,38 @@
>  
>  @c -----------------------------------------------------------------------
>  
> + at node Using foreign types from Mercury
> + at section Using foreign types from Mercury
> +
> +Types defined in foreign language can be defined in Mercury using 

s/foreign language/a foreign language/

Also s/defined in Mercury/accessed in Mercury/ ?

> @@ -5085,6 +5120,7 @@
>  
>  @menu
>  * Interfacing with C 		:: How to write code to interface with C
> +* Interfacing with .NET CLR	:: How to write code to interface with .NET CLR
>  * Interfacing with C# 		:: How to write code to interface with C#
>  * Interfacing with IL 		:: How to write code to interface with IL
>  * Interfacing with Managed C++ 	:: How to write code to interface with

This is in a section titled "language specific bindings".
All the other entries here are languages, but ".NET CLR"
is not really a language.  So I don't think it belongs here.

> +
> + at node Using pragma foreign_type for C
> + at subsubsection Using pragma foreign_type for C
> +
> +This pragma is currently not implemented for C backends.

s/not implemented for C backends/not supported for C/
(We should be talking about languages, not backends.)

Also it would be a good idea to mention here that the
`c_pointer' type can be used instead (giving an example).

> + at node Interfacing with .NET CLR
> + at subsection Interfacing with .NET CLR
> +
> +This section describes how to interface with the .NET Common Language
> +Runtime, as specified by the ECMA Common Language Infrastructure (ECMA
> +TC39/TG3) standards.

Currently these are only draft standards, not standards yet.

So I suggesting adding a footnote

	...
	TC39/TG3) standards at footnote{
		At the time of writing, these are only draft standards,
		not official ECMA standards.
	}.

Also I think this section describes how to interface with
code compiled for the .NET CLR, rather than how to interface
with the .NET CLR itself.

> + at c XXX
> +Currently much of this section is still undocumented, sorry.
> +
> + at menu
> +* Using pragma foreign_type for .NET CLR :: Declaring .NET CLR types in Mercury
> + at end menu
> +
> + at node Using pragma foreign_type for .NET CLR
> + at subsubsection Using pragma foreign_type for .NET CLR
> +
> +The .NET CLR @samp{pragma foreign_type} declaration is of
> +the form:
> +
> + at example
> +:- pragma foreign_type(il, @var{MercuryTypeName}, @var{DotNetForeignType}).
> + at end example

The language in this `foreign_type' declaration is `il'.
So why isn't this in the "interfacing with IL" section?

> +If the @var{MercuryTypeName} is the type of a parameter of a procedure
> +defined using @samp{pragma foreign_proc} for any of the .NET CLR
> +languages, it will be passed to user code as @var{DotNetForeignType}.

It's not clear what "user code" means here.

> +Futhermore, any exported (with @samp{pragma export}) Mercury
> +procedure

Fix the typo, and rephrase it:

	Furthermore, any Mercury procedure exported with @samp{pragma export}
	  ^

> will use @var{DotNetForeignType} as the parameter type for

s/parameter type/.NET CLR parameter type/

> +The CIL assembler syntax is used to specify type names for the .NET CLR
> +backend (this syntax is documented in the ECMA specifications for .NET).

The word "backend" shouldn't appear in this section of the language
reference manual, unless it is talking about implementation-specific
restrictions association with the Melbourne Mercury compiler.

I think what you mean here is that the CIL assembler syntax is used to
specify type names for `pragma foreign_import(il, ...)' declarations.

It would be appropriate to note here that in the current Mercury
implementation, the `il' form of the `pragma foreign_import' declaration
is only supported by the .NET CLR back-end.

[so far I've only reviewed the changes to doc/reference_manual.texi]

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