I’m trying to get documentation comments converted to HTML pages. Following the documentation of Dune on that matter, I simply install the odoc package and run dune build @doc. (Assuming that my library is public.)
I wrote the following library (mylib with a module Mylib):
(** Demo library *)
(** Increase number
@param x Number to increase
@returns Number [x] increased by one
*)
let inc x = x + 1
But the documentation in _build/default/_doc/_html/mylib/Mylib/index.html looks ugly when I open it with a webbrowser:
The headings “Parameter” and “Returns” aren’t even bold or somehow different from the remaining text content. Is this the default style, or did I do something wrong? Can I change this?
I noticed that the link in Dune’s documentation regarding the formatting rules refers to the OCaml manual (here), which seems to use ocamldoc (and not odoc).
I’m confused. Do I use odoc or ocamldoc when I write dune build @doc?
Are the @params and @returns annotations deprecated perhaps? The standard library API documentation doesn’t seem to have dedicated sections for arguments and/or return values.
Historically, documentation of functions is written like this (I’m showing an example of an interface file as typically the public documentation is there):
val inc : int -> int
(** [inc x] is [x] increased by 1. *)
The @param and @return tags are later additions to the markup language, and not really used as much. Although I find @since and @raise very helpful. So as such, the formatting for the first two tags is not really fleshed out.
ocamldoc is the name of the markup syntax for OCaml documentation comments, as well as the name of the legacy documentation tool. odoc is the preferred documentation tool.
This could be an issue on odoc’s issue tracker : Issues · ocaml/odoc · GitHub
We have limited resources so it might not get addressed quickly.
Should I prefer the “historical” style? Or is this work in progress and subject to change? Or is it not clear yet how it will be in the future?
I think you should prefer what was described as historical style. It is often named “equationnal style” and I think it is a nice way to explain what a function does, especially a pure one, as functions often are in OCaml.
The idea of this style of doc strings is to teach how one should read and understand code using the function. That is you show a function application and describe its return value and/or effects as a function of its parameters – that’s how you should read the code.
Compare and contrast @yawaramin doc’s string to the one you wrote with @param (in the source to avoid being distracted by the supbar rendering). Personally I find @yawaramin’s one much more palatable. Using @param, @return you veer towards descriptions for machines rather than humans in my opinion (also if you don’t have labels it may not be clear of which parameter you are talking).
I do want to note that sometimes machine-readable documentation is useful for language servers, which, for example, could suggest a description of a function parameter as it’s being typed. This isn’t as useful in OCamlland because we have partial application, etc. but I do think it suits some other languages well.
