.mli file usage

[enetsee]

We've been going back and forth for a while on where we should be using .mli files are where they are unnecessary. I've now asked a couple of questions related to this on OCaml discuss here and here and wanted to summarize my understanding and get some consensus on this.

The first question I asked was about why Jane Street use three files [X].ml, [X].mli and [X]_intf.mli in their libraries. The answer is basically that it saves repeating, and therefore having to update, signatures in two places. The approach is only needed when a module exposes a functor.

My second question was to clarify why you would use an interface file in three situations. The easy cases are:

• When you want to hide the implementation you clearly need to use one.
• When a file only exposes a module signature you do not need one.

The third case is where we have an implementation file but the interface doesn't hide anything. The response to my questions suggested that this is indeed discretionary but recommended avoiding using module type of which we do in a number of places at the moment. Another respondent suggested that .mli files are usually added when a module is matured and the Jane Street style guide recommends putting your docs in the .mli.

The final feedback was that there is no need to include 'index modules' like Common.ml or Middle.ml since dune generates this for you. This is true even in cases where you don't want to expose all the modules in the library since this can be handled using dunes private_modules stanza.

I asked about the impact of .mli on compilation times but this wasn't mentioned a pro/con by any respondents.

Based on this, my instinct is to:

1. Move to the Jane Street style of [X].ml, [X].mli and [X]_intf.mli for modules exposing functors
2. Remove usage of module type of
3. Remove 'index modules' (which should mostly take care of point 2).
4. Start to create .mli where the implementation is more settled and being to add docs there.

This would save us a few files (with point 3) but cost us a few with point 1. However, adopting 1 will help with maintenance.

@rybern @seantalts @VMatthijs I'd like to get your thoughts on this before making any changes.

[seantalts]

That discussion happened quickly! It looks like they don't like module type of for reasons that don't apply to most of our code, given that we aren't publishing opam packages and don't use that many functors,

The problem is with arrows as always, i.e., with functors. Since module types may occur on both sides (being either an argument, or a resulting type) we may have the variancy problem

That said, the only place we use module type of is in these index modules, Common and Middle, so we are already going to remove them all via point 3 as you note.

I'm happy with 1, 2 annotated with "for functors", and 3. I asked a question on one of those threads about 4, given that ocamldoc can read doc from .ml files in the absence of an .mli file, is there any benefit to creating an .mli file for an .ml file that doesn't need to hide anything yet.

[enetsee]

I asked a question on one of those threads about 4, given that ocamldoc can read doc from .ml files in the absence of an .mli file, is there any benefit to creating an .mli file for an .ml file that doesn't need to hide anything yet.

I really don't understand OCaml sometimes... I feel a lot happier with not having the interfaces for case 4 now. I had an inkling that it would slow compile times down but, given no one has said it it does, I don't really get the design decision that led to .mli files! It would have been much better to have an exporting declaration like Haskell rather than a second file type which you might sometimes need...

[seantalts]

Yeah, I definitely thought .mli files were for compile performance only, but that would have been for a super simplistic compiler that ocaml has presumably since moved past, haha. Maybe it's a legacy thing. And someone replied saying that they tend to use .mli files as the doc for the project in their editor, which could make sense (though I'm generally a huge fan of getting a decent editor set up that handles that for you). Given that .mli files obstruct "goto definition" in a good editor I'm ~1% biased against them if there's no need to hide functionality from the .ml file. And agreed having some kind of exporting declaration would seem to be the obvious way to go here...

[rybern]

This sounds good to me, very happy to go along with their best practices. I still miss having types on everything, but fixing my editor to do that has helped reading code somewhat.