1

Simply put, let us say I have the following OCaml file called test.ml:

(**
    [Test] is a sample module for showing the problem I am having with @ tags with OCamlDoc
*)

(**
    [id] is the identity function. For any argument [x], [id x] is [x].
    @param x The argument, which will be returned
    @return The argument [x]
*)
let id (x: 'a): 'a = x

If I run the command ocamldoc -html -all-params -colorize-code test.ml to get the documentation for the Test module, I get the following result:

documentation

As can be seen, for the parameter information, it puts () as the name of the parameter and does not include a description for the parameter for some reason.

I am unsure why the parameter name and description are not properly showing up.

Gigi Bayte 2
  • 838
  • 1
  • 8
  • 20

2 Answers2

3

If you write let id x = x the display is correct:

enter image description here

The problem is that ocamldoc will not display @param if you provide a tag that doesn't match a named argument but it's not able to extract a named argument from (id : type).

This is a known bug but sadly nobody touched it so... https://github.com/ocaml/ocaml/issues/8804

Lhooq
  • 4,281
  • 1
  • 18
  • 37
  • I see. It is unfortunate that it has not been touched and has even been closed. As per @octachron, I will be looking into `odoc`. – Gigi Bayte 2 Nov 17 '20 at 14:16
2

As ocamldoc's part-time maintainer, there are very few reasons to still use ocamldoc when odoc is available, even more so when writing new documentation.

Ocamldoc's handling of param tag is far too complex for its own good: ocamldoc tries to peek at the definition of the function and only accepts param tag that matches the argument that it can recognize. Here, it fails on explicit type annotation.

octachron
  • 17,178
  • 2
  • 16
  • 23