[m-rev.] for review: clarify how foreign_enum values are specified in C

[Julien Fischer]

Hi Zoltan,

On Sat, 25 Sep 2021, Zoltan Somogyi wrote:

> 2021-09-25 15:33 GMT+10:00 "Julien Fischer" <jfischer at opturion.com>:
>> @@ -9551,8 +9551,13 @@ as the use of @samp{pragma foreign_type} results in more type-safe code.
>>  @subsubsection Using pragma foreign_enum for C
>>
>>  Foreign enumeration values in C must be constants of type @code{MR_Integer}.
>> -They may be specified as either integer literals
>> -or via preprocessor macros that expand to integer literals.
>> +A foreign enumeration value may be specified by one of the following:
>> + at itemize
>> + at item An integer literal.
>> + at item An enumeration constant.
>> + at item A preprocessor macro that expands to either an integer literal or
>> +an enumeration constant.
>> + at end itemize
>>
>>  @node Using pragma foreign_export_enum for C
>>  @subsubsection Using pragma foreign_export_enum for C
>
> That is fine as far as it goes. But if this is in response to the
> m-users emails from Sean Charles today,

Somewhat, it was an omission I noticed when looking at the SDL headers
after reading his mail.

> then I think what would help more is a statement about the C type that
> programmers should use for a type defined by a pragma foreign enum.

If you are referring to how such values are passed across the Mercury-C
boundary, then as documented they have type MR_Word.  If you are asking
what C type should be used, for example, to declare local variables for
foreign_enum values in C code, there is no one answer (since you are
probably dealing with a C API that has its own ideas about that).

> Section 14.6 of the reference manual does not seem to have one.

Section 15.6 does not address the target language level aspects fo
foreign enum pragmas; those are covered in target language specific
sections for foreign enums later on, and those are the appropriate
place for such statements.

Julien.