odoc driver cannot find source for Dune `include_subdirs qualified` modules

[katrinafyi]

Sometimes, Dune will generate .ml-gen wrapper modules that look like this:

(* generated by dune *)

(** @canonical Foolib.Foo *)
module Foo = Foolib__Foo

When installing, Dune will copy these files into the install prefix using a .ml suffix and, possibly, a different path. To locate the installed source files, odoc driver has to correlate the source location recorded in the .cmt, which is in terms of .ml-gen, with the installed .ml path. This is done at https://github.com/ocaml/odoc/blob/v3.1/src/driver/ocamlobjinfo.ml#L6 and it works for the simple case of Dune's top-level library module wrapping.

However, Dune's (include_subdirs qualified) option will generate additional wrapper modules for intermediate directories in the directory tree. The source files for these intermediate ml-gen files cannot be found by odoc driver.

These are some .cmt paths, the recorded source file, and the expected actual source path for the two cases:

• for toplevel wrapper module: foolib.cmt -> lib/foolib.ml-gen -> ./foolib.ml (works now)
• for include_subdirs: foolib__Foo.cmt -> lib/foolib__Foo.ml-gen -/-> ./foo/foo.ml (doesn't work right now)

This could probably be fixed by (trying to) translate the __ into / to obtain the correct subfolder path to the installed .ml file. At the moment, it assumes every .ml file is in the same directory as the .cmt file.

I have been using this dune test case as an example for testing: https://github.com/ocaml/dune/tree/5b109c3cb8bf4492415168f7597405aa13bfb569/test/blackbox-tests/test-cases/include-qualified/basic.t. You will need to add a package declaration and a public name to have it installed. Let me know if you want me to upload this.

[katrinafyi]

I have the start of a fix at: https://github.com/rsc-s/odoc/tree/subdirs.

This works but the files in subdirectories are reduced to their basename, so there could be a risk of conflicting with a same-named file in a different subdirectory.