Language manual: floatarray documentation?

Learning
1

Hi everyone,

I put myself in the shoes of a beginner looking for the predefined types in the OCaml manual.

The floatarray type has been introduced since release 4.6.0 to make the choice between boxed vs. unboxed representations easier, but I cannot find any description of it in the language manual, despite it being mentioned in Chapter 22 Interfacing C with OCaml and in the documentation for some modules.

Is this a gap in the manual, or am I missing something?

2

What kind of documentation are you looking for? The type and the associated module are documented in the manual OCaml library : Float.Array (though I agree there is not much discussion of what floatarray is).

The thing is that 99.9% of OCaml users are using the standard mode (“flat-float-array”) which renders the use of floatarray essentially unnecessary. If memory serves, last time this was discussed, there was no agreement among the maintainers about turning off this optimization by default.

Cheers,
Nicolas

3

Hi nojb,

the point of my question is: imagine a newcomer who’s looking at type t = floatarrayand thinking “What the heck floatarray stands for? Is this just a typo, does it mean float array or is it somewhat different? Let me read TFM…”

Well, the The Fabulous Manual says nothing about it: our newcomer will get infos about float, ‘a array and no more.

4

Right. The answer to your question then is that indeed there is no beginner-friendly explanation of what floatarray is for in the manual, at the moment. Adding a bit more explanation at the top of the Float.Array module would be the simplest way of addressing this concern. PRs in this direction would be welcome.

Cheers,
Nicolas

2 Likes
5

The manual is laconic on the subject but it does say that Float.Array.t is a packed representation of float arrays: OCaml library : Float.Array .

6

Yep. The unusual thing is that it makes use of floatarray without defining its meaning. floatarray is not listed in the type index neither.

7

I made an attempt in this direction over at Expand doc of Float.Array by nojb ¡ Pull Request #14586 ¡ ocaml/ocaml ¡ GitHub. Feel free to chime in.

Cheers,
Nicolas

1 Like