`{!Ocaml_operators}` in different styles

On doc page OCaml library : Stdlib, v4.14

  • When used in a normal doc entry, the interpreted result of {!Ocaml_operators} has a background color.
  • When used in a doc entry for deprecated operator (maybe also functions and types, not checked), there’s no background color.

Is this difference on purpose?

PS: It seems this difference came with the current html design, which is deployed since v4.12.

PS2: You won’t find docs for Stdlib.( & ) and Stdlib.( | ) in the latest codebase because they were already removed in preparation for release v5.0.0, see Remove deprecated functions by nojb · Pull Request #10867 · ocaml/ocaml · GitHub .

From browser’s “Inspect” utility, I find docs for normal operator are wrapped in a <p> tag which then meet the background-color css set for .api p code. Docs for deprecated operators are not wrapped in a <p> tag, hence the <code> has no background color.

<div class="api">
  <!-- doc for normal operator, for example Stdlib.(&&) -->
  <div class="info ">
    <div class="info-desc">
      <p> [...],  see <a href="Ocaml_operators.html">
        <code class="code">
          <span class="constructor">Ocaml_operators</span>
      </a> for more information.</p>
  <!-- doc for deprecated operator, for example Stdlib.(&) -->
  <div class="info ">
    <div class="info-deprecated">
      [...], see <a href="Ocaml_operators.html">
        <code class="code">
          <span class="constructor">Ocaml_operators</span>
      </a> for more information.
/* excerpted from styles.css */ 
.api p code, .api li code {
    background-color: #ebf2f9;

I don’t think that the difference is here on purpose. At least, I missed that difference when reviewing the last manual style update. And since the manual is due for another graphical chart update to better fit the new ocaml.org, I am not sure if I will have the time to fix the issue.

It seems the difference came from ocamldoc directly, and it’s the latest manual style that makes the difference more observable.

I’m new to OCaml and below is just my “random” attempt:

Prepare a file mystdlib.mli

external ( && ) : bool -> bool -> bool = "%sequand"
(** The boolean 'and'. Evaluation is sequential, left-to-right:
   in [e1 && e2], [e1] is evaluated first, and if it returns [false],
   [e2] is not evaluated at all.
   Right-associative operator,  see {!Ocaml_operators} for more information.

external ( & ) : bool -> bool -> bool = "%sequand"
  [@@ocaml.deprecated "Use (&&) instead."]
(** @deprecated {!Stdlib.( && )} should be used instead.
    Right-associative operator, see {!Ocaml_operators} for more information.

Then run ocamldoc -html mystdlib.mli. [1] In the output file Mystdlib.html, I find the problem reproduces:

  • doc entry for ( && ) is wrapped in <p> tag, while
  • doc entry for deprecated ( & ) is not wrapped in <p> tag.

GitHub’s “View git blame” utility shows the <p> tag is added by PR MPR#7352,7353: ocamldoc, better paragraphs in html · ocaml/ocaml@d069dbe · GitHub.

[1] I’m following the cs3110 book, which uses ocaml-base-compiler.4.12.0 (Installing OCaml — OCaml Programming: Correct + Efficient + Beautiful). Hence my ocamldoc --version gives 4.12.0.