MPR#5852: Ocamlbuild does not pass .ml files to ocamldoc when there is an .mli file present

[damiendoligez]

PR transferred from https://caml.inria.fr/mantis/view.php?id=5852 [original reporter: @23Skidoo]

I want to include source code in my generated docs. This works when I invoke ocamldoc on the command-line like this:

ocamldoc -I _build -html -keep-code -colorize-code *.{ml,mli} -d .docdir

. However, I'm having troubles integrating this with ocamlbuild.

I'm using the following code in myocamlbuild.ml:

open Ocamlbuild_plugin;;

dispatch begin function
  | After_options ->
      Options.ocamldoc := S[A"ocamldoc"; A"-keep-code"; A"-colorize-code"]

| _ -> ()
end

But this only includes the source for files with no corresponding interface file - it looks like ocamlbuild refuses to pass .ml files to ocamldoc when there is an .mli file present. It'd be nice if it was possible to integrate ocamldoc -keep-code with ocamlbuild.

[Armael]

This happens because of the way ocamlbuild uses ocamldoc to build documentation, using intermediate odoc files produced using the -dump option of ocamldoc.

Currently, the process is as follows:

• The user writes a foo.odocl file listing modules to be documented;
• The user invokes ocamlbuild foo.docdir/index.html to build html documentation;
• This triggers the corresponding ocamlbuild rule, which runs Ocaml_tools.document_ocaml_project;
• For each module of foo.odocl, Ocaml_tools.document_ocaml_project builds an intermediate .odoc file, which "stores the result of ocamldoc processing on a source file". This .odoc file is obtained by calling ocamldoc with the -dump option;
• when all .odoc files are created, an single ocamldoc invocation builds the documentation, and is passed all the .odoc files as arguments using -load ....

The issue is that exactly one .odoc file is build for each module. The fact that ocamldoc doesn't see the contents of a .ml if a .mli is present is because the rule producing a .odoc from a .mli has higher priority than the one producing a .odoc from a .ml.

For -keep-code to work as expected, we would need to run ocamldoc -dump ... on both the .ml and .mli, producing two different output files (.odoc and .odoci?). Then these two would be eventually fed to ocamldoc using -load — at this point ocamldoc would have the possibility of ignoring the contents of the .ml (default behavior), or using it along with the .mli (-keep-code).

[Armael]

I'd like to implement a fix along the lines of the last paragraph, but I'm not sure how at the moment. The difficulty is that, now, we would need to express that for each module of foo.odocl, we would like to build a .odoc and a .odoci. We would like to build both if possible, but if building one is not possible then it's still fine, as long as building the other one works.

I'm not sure how to encode this in ocamlbuild rules or how to implement this in Ocaml_tools.document_ocaml_project.

[whitequark]

Maybe you could gate the behavior on odoc_keep_code tag?