Stdlib doc: inconsistent spaces around operators, (==) vs ( == )

On doc page OCaml library : Stdlib,

which looks not consistent.

Related source lines: ocaml/stdlib.mli at 40113fbc73930b41a7a2df468de18c94feeefdf5 · ocaml/ocaml · GitHub

Those spaces were added 12 years ago, by commit 49f84679d2c5816cf557f28e5878c2a355b94eb6 in github repo ocaml/ocaml. It warns that new user can post at most 2 links so I have to convert the third one in plain text. The commit suggested there’re two cases for Stdlib.(=) (it’s mentioned as ( = ) in doc for Stdlib.(>=)).

1 Like

Good catch! I encourage you to open an issue upstream at Issues · ocaml/ocaml · GitHub, or, even better, propose a PR to fix the inconsistency.


Note that this is an ocamldoc/odoc issue.

Sorry I’m a bit confusing. Do you mean that (ideally) {!Stdlib.( == )} should be converted/interpreted to

<a href="Stdlib.html#VAL(==)"><code class="code">( == )</code></a>

rather than the current

<a href="Stdlib.html#VAL(==)"><code class="code">(==)</code></a>

Yes. As you can see the source you linked to is consistent. The rendering of operators by ocamldoc (and odoc) seems to remove the spaces – I vaguely remember this being done on purpose for a reason or another but I can’t dig out the discussion.

From the commit page on github, the change from [(==)] to [( == )] and from [(=)] to [( = )], in stdlib/pervasives.mli, is released with OCaml v4.0.0.

I checked the manual for v3.12.1, which is the only one prior to v4.0.0 listed in OCaml’s release page (ocaml dot org/releases, two-link restriction again), and found {!Pervasives.( == )} in stdlib/pervasives.mli had already been interpreted to

<a href="Pervasives.html#VAL(==)"><code class="code">(==)</code></a>

with spaces trimmed.

Thus even if spaces were removed on purpose, it was perhaps more than a decade ago.

Related links:

  • Doc for Pervasives.( == ), v3.12 2011-07-04 Pervasives
  • Doc for Pervasives.( == ), v4.00.1 2012-10-05 Pervasives