`{!Ocaml_operators}` in different styles

Learning
1

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 .

image
image789×436 76.4 KB

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>
        </code>
      </a> for more information.</p>
    </div>
  </div>
  
  <!-- 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>
        </code>
      </a> for more information.
    </div>
  </div>
</div>

/* excerpted from styles.css */ 
.api p code, .api li code {
    background-color: #ebf2f9;
}
2

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.

3

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.