[Caml-list] A confusing sentence in documentation of Gc.finalise.

[Caml-list] A confusing sentence in documentation of Gc.finalise.

[Evgeny Roubinchtein]

[-- Attachment #1: Type: text/plain, Size: 1438 bytes --]

Dear OCaml users and developers,

The description of Gc.finalise (as can be seen, for example, at
http://caml.inria.fr/pub/docs/manual-ocaml/libref/Gc.html), contains the
following statement:

>  The results of calling String.make
<http://caml.inria.fr/pub/docs/manual-ocaml/libref/String.html#VALmake>,
Bytes.make
<http://caml.inria.fr/pub/docs/manual-ocaml/libref/Bytes.html#VALmake>,
Bytes.create
<http://caml.inria.fr/pub/docs/manual-ocaml/libref/Bytes.html#VALcreate>,
Array.make
<http://caml.inria.fr/pub/docs/manual-ocaml/libref/Array.html#VALmake>, and
ref
<http://caml.inria.fr/pub/docs/manual-ocaml/libref/Pervasives.html#VALref>
are guaranteed to be heap-allocated and non-constant *_except when the
length argument is 0*_ [emphasis mine].

The reason I find it confusing is that ref does not take, a "length
argument."

My semi-educated guess is that the intended meaning is something like, "If
the length argument of a call to String.make, Bytes.make, Bytes.create, or
Array.make is not 0, the result is guaranteed to be heap-allocated and
non-constant.  The result of a call to ref is [always] guaranteed to be
heap-allocated and non-constant."

Could someone either confirm my guess or tell me that I am mistaken?  Also,
if my guess is, in fact, accurate, what's the best way to add my suggested
revision to the "to consider for inclusion into the next version of the
manual" list?

Thank you in advance!

-- 
Best,
Zhenya

[-- Attachment #2: Type: text/html, Size: 2114 bytes --]

Re: [Caml-list] A confusing sentence in documentation of Gc.finalise.

[Gabriel Scherer]

Yes, your guess is correct. The best way to get this fixed is to send
a pull request against stdlib/gc.mli:

  https://github.com/ocaml/ocaml/

From the root of the repository, you can test .mli changes to the
manual by using the target

    make html_doc

(contributed by Simon Cruanes) and then opening
./ocamldoc/stdlib_html/index.html in a web browser.


On Sun, Jun 18, 2017 at 9:19 AM, Evgeny Roubinchtein
<zhenya1007@gmail.com> wrote:
> Dear OCaml users and developers,
>
> The description of Gc.finalise (as can be seen, for example, at
> http://caml.inria.fr/pub/docs/manual-ocaml/libref/Gc.html), contains the
> following statement:
>
>>  The results of calling String.make, Bytes.make, Bytes.create, Array.make,
>> and ref are guaranteed to be heap-allocated and non-constant _except when
>> the length argument is 0_ [emphasis mine].
>
> The reason I find it confusing is that ref does not take, a "length
> argument."
>
> My semi-educated guess is that the intended meaning is something like, "If
> the length argument of a call to String.make, Bytes.make, Bytes.create, or
> Array.make is not 0, the result is guaranteed to be heap-allocated and
> non-constant.  The result of a call to ref is [always] guaranteed to be
> heap-allocated and non-constant."
>
> Could someone either confirm my guess or tell me that I am mistaken?  Also,
> if my guess is, in fact, accurate, what's the best way to add my suggested
> revision to the "to consider for inclusion into the next version of the
> manual" list?
>
> Thank you in advance!
>
> --
> Best,
> Zhenya