[m-rev.] for review: reference manual clarifications and fixes

[Julien Fischer]

For review by anyone.

(I have another upcoming change that further extends the description
of foreign_export pragmas for C by adding some examples and also covering
what happens with existential types.)

Branches: main

Fix some reference manual things related to the foreign language interface.

doc/reference_manual.texi:
 	s/C code/foreign code/ in the description of the may_call_mercury
 	attribute.

 	Make it clear that MR_Integer is a signed type.

 	Update the descriptions of MR_String and MR_Char.

 	In the description of foreign_export pragmas for C, don't
 	describe type variables as polymorphic.  Also mention that
 	the compiler prepends on extra argument for each _distinct_
 	type variable.

Julien.

Index: reference_manual.texi
===================================================================
RCS file: /home/mercury/mercury1/repository/mercury/doc/reference_manual.texi,v
retrieving revision 1.463
diff -u -r1.463 reference_manual.texi
--- reference_manual.texi	20 May 2011 04:16:50 -0000	1.463
+++ reference_manual.texi	10 Jun 2011 06:17:43 -0000
@@ -6335,7 +6335,7 @@
  as in the above example, then you can use @samp{will_not_call_mercury}
  in place of @samp{may_call_mercury} in the declarations above.
  This allows the compiler to use a slightly more efficient calling convention.
-(If you use this form, and the C code @emph{does} invoke Mercury code,
+(If you use this form, and the foreign code @emph{does} invoke Mercury code,
  then the behaviour is undefined --- your program may misbehave or crash.)

  If there are both Mercury definitions and foreign_proc definitions for 
@@ -6684,12 +6684,12 @@
  @code{MR_Integer}, @code{MR_Float}, @code{MR_Char},
  and @code{MR_String} respectively.

-In the current implementation, @samp{MR_Integer} is a typedef for an integral
-type whose size is the same size as a pointer of type @samp{void *};
+In the current implementation, @samp{MR_Integer} is a typedef for a signed
+integral type whose size is the same size as a pointer of type @samp{void *};
  @samp{MR_Float} is a typedef for @samp{double} (unless the program and the
  Mercury library was compiled with @samp{--single-prec-float}, in which case it
-is a typedef for @samp{float}); @samp{MR_Char} is a typedef for @samp{char};
-and @samp{MR_String} is a typedef for @samp{MR_Char *}.
+is a typedef for @samp{float}); @samp{MR_Char} is a typedef for a signed 
+32-bit integral type and @samp{MR_String} is a typedef for @samp{char *}.

  Mercury variables of type @code{int}, @code{float}, @code{char}, or
  @code{string} are passed to and from C as C variables whose type is
@@ -7671,14 +7671,14 @@
  call the polymorphic procedures, and export them, rather than exporting the
  polymorphic procedures.

-If you do export a polymorphically typed Mercury procedure, the compiler
-will prepend one @samp{type_info} argument to the parameter list of
-the C interface function for each polymorphic type variable in the
-Mercury procedure's type signature.  The caller must arrange to pass
-in appropriate @samp{type_info} values corresponding to the types
-of the other arguments passed.  These @samp{type_info} arguments can
-be obtained using the Mercury @samp{type_of} function in the Mercury
-standard library module @samp{type_desc}.
+If you do export a polymorphically typed Mercury procedure, the compiler will
+prepend one @samp{type_info} argument to the parameter list of the C interface
+function for each distinct type variable in the Mercury procedure's type
+signature.
+The caller must arrange to pass in appropriate @samp{type_info} values
+corresponding to the types of the other arguments passed.  These
+ at samp{type_info} arguments can be obtained using the Mercury @samp{type_of}
+function in the Mercury standard library module @samp{type_desc}.

  To use the C declarations produced see @ref{Using pragma foreign_decl for C}.


--------------------------------------------------------------------------
mercury-reviews mailing list
Post messages to:       mercury-reviews at csse.unimelb.edu.au
Administrative Queries: owner-mercury-reviews at csse.unimelb.edu.au
Subscriptions:          mercury-reviews-request at csse.unimelb.edu.au
--------------------------------------------------------------------------