Search code examples
ocamldocumentationdocumentation-generationcode-documentationocamldoc

ocamldoc not properly displaying parameter names or description with @param

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.

Solution

  • 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