[m-dev.] documenting parts of Mercury's C runtime interface

[Julien Fischer]

On Thu, 31 Jan 2008, Mark Brown wrote:

> On 31-Jan-2008, Julien Fischer <juliensf at csse.unimelb.edu.au> wrote:
>> Most Mercury bindings to C (or C++) libraries need to make some use of the
>> facilities provided by the runtime, e.g. for memory allocation in C code
>> using
>> the GC, making aligned string copies, or extracting an underlying C file
>> stream from a Mercury one.
>>
>> Currently, none of this stuff is really documented outside of runtime
>> code itself.  For most of the runtime this is desirable since we want
>> the freedom to change it without respect to backwards compatability,
>> but some usage of the runtime functionality has become some prevalent
>> in library bindings and other code that makes heavy use of the C interface
>>  that it really does need to be documented properly.
>>
>> Should this be done in the reference manual, the user's guide, or a
>> separate
>> guide to the runtime?  Which would people prefer?
>
> It should go near the foreign language interface documentation, eg a
> section of the reference manual.

I see the purpose of the reference manual to define the language.
The C interface to the runtime is an implementation detail, I don't
see it as part of the language.

> It would also make sense to write a "Foreign language interface manual",
> which would cover the language specific details that are currently in the
> reference manual, and also include a section on the runtime API.

Leaving the generic foreign langugage stuff in the reference manual
and shifting the language specific bindings to a separate document?

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