Hi Daniel,
You're absolutely right in all details. And yes the devil is in details. I should be more precise and disclose all the ingredients of my recipe. Indeed, we are not using module aliases, and yes hiding the cmi file, of course, will not fix the flat namespace of compilation units. So, the solution that we are using for our libraries in CMU is pretty simple, for a library/project named LIB do the following:
1. prefix all internal modules with the `LIB_`
2. provide a public module `LIB.ml` that reexports some of the internals
3. describe the public interface in `LIB.mli`
4. do not install `cmi` and `mli` files for the internal modules.
The public interface, of course, should not mention any internals.
Given a concrete example, suppose we want to implement a Monad library and name it `monad`. The project structure would be the following:
```
monad_state.mli
monad_reader.mli
...
monad.mli
```
```
include Monad_types
module State = Monad_state
module Reader = Monad_reader
...
```
The contents of the `monad.mli`
```
(** Lot's of docs *)
module type S = sig
type 'a t
val map : 'a t -> ('a -> 'b) -> 'b t
val bind : 'a t -> ('a -> 'b t) -> 'b t
val return : 'a -> 'a t
...
end
...
module State : sig
type ('a,'e) t
include S2 with type ('a,'e) t := ('a,'e) t
...
val run : ('a,'e) t -> 'e -> 'a * 'e
end
...
```
The most controversial part is the duplication of the `mli` files. Of course, one can omit `mli` for the internals, but I myself is a strong proponent of writing mli files, and will not go that way. Thus, we decided to support the two sets of mli files. The internal set, describes our internal developer's interface, that is sometimes richer and less stable than the external. The external defines the public API, that is stable and versioned, it also must be well-documented. The internal interfaces usually do not contain documents, except technical notes and implementation details.
For a real life example, look at the graphlib library:
P.S. This is not the only solution. Another, probably better, solution, that I was using before, is to use packing. It is much nicer in the sense, that it solves the flat namespace issue. However, OASIS messes with the packed modules, so we were forced to use this, more ad-hoc approach.
P.P.S. Strictly speaking we do not need to install even the `cmx` of the internal modules, however, their absence will prevent cross-module optimization if my understanding of the latter is correct.
Best wishes,
Ivan