0000784: wishes concerning documentation

View Issue Details [ Jump to Notes ]

[ Issue History ] [ Print ]

Project

Category

View Status

Date Submitted

Last Update

0000784

OCaml

OCaml general

public

2002-01-08 09:25

2002-11-25 15:46

Reporter

administrator

Assigned To

Priority

normal

Severity

feature

Reproducibility

always

Status

acknowledged

Resolution

open

Platform

OS Version

Product Version

Target Version

Fixed in Version

Summary

0000784: wishes concerning documentation

Description

Full_Name: Winfried Dreckmann
Version: Ocaml 3.04
OS: Suse Linux 6.4 on PowerPC
Submission from: t3o901p49.telia.com (62.20.253.49)

These are some wishes concerning the documentation. At the end I will also
report what I believe is a bug. This is all low priority, but I am curious to
get hints.
I am using the low level C interface, and I want to write code which is
maximally compatible with future versions of Ocaml. As I understand it, the
contents of the C interface header files may change. The features which are
documented may also change, but less so. Therefore, I would like to see

(1) the macro "Max_wosize" documented,
(2) a documented macro or some other way to make the maximal size of a custom
block accessible to C functions,
(3) the macros "Max_long" and "Min_long" documented (accessible through
"max_int" and "min_int" from the core library, but this is clumsy),
(4) a documented macro or some other way to get the maximal size of an Ocaml
string (accessible through Sys.max_string_size, but again clumsy).

Also, it seems implicitly clear that a "value" is always a C long integer. A
candidate for explicit documentation?

I realize that the size restrictions for marshaling are still a little vague,
even in the source code. Trying to understand the source code ("intern.c",
"extern.c") I made the following observation: It seems possible to read a
marshaled block on a 32 bit machine, even it it was created on a 64 bit machine
(good!) with a size exceeding the 32 bit limits (dubious). Moreover, the header
on the 32 bit machine will be wrong (wrong size bits), and I guess some things
(toplevel "compare" ?) will not always work correctly.

I think the low level C interface is an excellent feature. In principle, I hope
that much more can be documented, but I see the difficulties.

Winfried Dreckmann

Issue History
Date Modified	Username	Field	Change
2005-11-18 10:13	administrator	New Issue

Notes
(0000121) administrator (administrator) 2002-11-25 15:46	Wishes on doc and mlvalues.h: reasonable, to be implemented. Bug with input_value on blocks >= 4 Mwords fixed 2002-11-25 by XL.

Relationships