Why does ocamldoc fail on unbound modules?

Question

Here is an example interface test.mli, commented with ocamldoc-style comments:

(** ocamldoc module comment *)
open MissingModule;;
(** ocamldoc function comment *)
val test : unit;;

If I run the command ocamldoc test.mli, I get the following error:

File "test.mli", line 2, characters 0-9:
Error: Unbound module MissingModule
1 error(s) encountered

Why should a documentation generator care about unbound modules?

Answer 1

That's because ocamldoc fully qualifies type names. The file:

open MissingModule

val f: foo -> unit

is translated to

val f: MissingModule.foo -> unit

And MissingModule.foo becomes a nice cross-reference to the definition of foo in MissingModule (if missingModule.mli is given as argument to ocamldoc).

And to complete the answer, in order to fully qualify type idents, you need to type the file you are processing. So ocamldoc needs to be able to access to the corresponding .cmi files.