Getting resulting sig and struct of a complex modular program

Learning
1

The OCaml module system lets create a very modular program with quite unlimited complexly nested sig and struct, while avoiding redundancy.
But the resulting documentation reflects exactly that, which makes it hard to read, resulting in jumping from one sig (or struct) to another. It may give headache and especially provoke mistakes when writing an expression with illegal type.

What is the straightest manner to get the resulting signature and structure of an OCaml program:

  • in its generated documentation
  • from the toplevel (it seems roughly to work with #show_module module-path but it sometimes has weird behavior/result)

The error messages are also more complex, revealing the modular structure. It can even be harder to understand when polymorphic variants are used!
Is there a way to limit that burden?
One simplistic idea would be to program in a modular way, then to “flatten” the whole program in order to let him expose the resulting sig/struct.
Is that idea sensible, and how to simply do that?

Thanks.

2

If you are interested in generating the documentation of such a structure - this is not an easy problem and was the topic of a talk at this year’s OCaml Workshop: The final pieces of the OCaml documentation puzzle

Rendering OCaml document is widely known as a very difficult task: The ever-evolving OCaml module system is extremely rich and can include complex set of inter-dependencies that are both difficult to compute and to render in a concise document. Its tasks are even harder than the typechecker as it also needs to keep track of documentation comments precisely and efficiently. As an example, signatures such as include F(X).T and destructive substitutions were never handled properly by any documentation generator.

2 Likes