[m-rev.] for review: documentation for pragma foreign_type

[Fergus Henderson]

On 29-Oct-2001, Tyson Dowd <trd at cs.mu.OZ.AU> wrote:
> doc/reference_manual.texi:
> 	Documentation for pragma foreign_type.
...
> Index: doc/reference_manual.texi
> ===================================================================
> RCS file: /home/mercury1/repository/mercury/doc/reference_manual.texi,v
> retrieving revision 1.204.2.11
> diff -u -r1.204.2.11 reference_manual.texi
> --- doc/reference_manual.texi	2001/10/17 12:31:10	1.204.2.11
> +++ doc/reference_manual.texi	2001/10/29 05:46:15
> @@ -4738,6 +4738,9 @@
>  * Adding foreign definitions::         How to add definitions of
>    				       entities in other programming
>  				       languages.
> +* Adding foreign types::               How to add declarations of
> +  				       types defined in other programming
> +				       languages.

`foreign_type' is more closely analagous with `foreign_proc' rather
than `foreign_decl', but this is not at all clear from the section titles
there.

I suggest changing the menu name there to

	Using foreign types from Mercury:: How to use a type defined in
					a different programming language
					in Mercury code.

and perhaps moving it to immediately before or after "Calling foreign
code from Mercury".

> + at node Adding foreign types
> + at section Adding foreign types
> +
> +Types defined in foreign language can be declared in Mercury using 
> +a declaration of the form
> +
> + at example
> +:- pragma foreign_type(@var{MercuryTypeName}, @var{BackendDescriptor}).
> + at end example
> +
> +This declaration introduces a new abstract type in Mercury which is a
> +synonym for a type defined in the specified backend language.
> + at var{BackendDescriptor} is a backend specific parameter, and defines how
> +the foreign type is mapped for a particular backend.  
> +Different backends support different sets of foreign languages, and so
> +the mapping of the foreign type to individual foreign languages is also 
> +defined by the backend specific code in the language specific
> +information below.
> +
> + at var{MercuryTypeName} is treated as an abstract type at all times in
> +Mercury code.
> +However, if @var{MercuryTypeName} is one of the parameters of a
> +foreign_proc, it will be marshalled as a foreign type as specified by
> + at var{BackendDescriptor}.

This whole section should be rewritten assuming that the reader has no idea
what the word "backend" means.

"marshalled" should also be explained.

The description of the semantics sounds wrong to me.  I thought we agreed
that we should require a Mercury declaration of the type,

	:- type @var{MercuryTypeName}.

and that the `pragma foreign_type' declaration did not declare a new
type (as the documentation above states), but instead just gave some
details about how that type was implemented.

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

I suggest putting `pragma foreign_proc' inside @samp{...} here.

> +Futhermore, any externally visible Mercury procedure will use
> + at var{DotNetForeignType} as the parameter type for parameters with
> + at var{MercuryTypeName}.

s/with/whose Mercury type is/

> +Since there is no universal syntax for .NET types, we use the Mercury
> +module qualifier as a namespace separator for the .NET namespaces.
> +Currently on the .NET backend only classes are supported using the
> +foreign_type pragma, and hence the only supported syntax for
> +DotNetForeignType is @samp{class(ClassName)}.
> +
> +For example:
> +
> + at example
> +:- pragma foreign_type(xmldoc, 
> +	il("System.Xml", class('System__Xml__XmlDocument'))).
> + at end example
> +
> +ensures that on the IL backend the mercury type @samp{xmldoc} is
> +represented marhsalled by the backend as @samp{System.Xml.XmlDocument}.

When you say that "only classes are supported", what does this exclude?

Does it work for value classes?

The explanation there refers to both the "IL backend" and the
".NET backend".  What's the difference?

-- 
Fergus Henderson <fjh at cs.mu.oz.au>  | "... it seems to me that 15 years of
The University of Melbourne         | email is plenty for one lifetime."
WWW: <http://www.cs.mu.oz.au/~fjh>  |     -- Prof. Donald E. Knuth
--------------------------------------------------------------------------
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
--------------------------------------------------------------------------