RE: [Caml-list] automatic extaction of the .mli (and a little more) from the .ml

[David Allsopp <dra-news@metastack.com>]

Romain Bardou wrote:
> I also used to believe the .mli file should be somehow included in the .ml
> file. Now I don't.

+1, FWIW! It's easy to start without the .mli when prototyping and then add it as things mature.
 
> But if you design such a tool, here are some things to consider.
> 
> - Using numbers to order stuff creates some issues of scalability. In
> particular, inserting a declaration between #3 and #4 may require you to
> move #4 to #5, #5 to #6 and so on, which (in particular if everything is
> not in the right order in the implementation) can prove more annoying than
> reordering stuff in an .mli.

This is horrible, IMO - any design decision which looks like it'll *require* refactoring support from an editor to be able to work with it strikes me as a bad design decision. If you have hundreds of these in a file, at some point you'll need a "renumber everything" macro.

I have wondered if this problem is perhaps looked at the wrong way around - in other words, the complaint takes the form "how can we export to the .mli file automatically" rather than "how can we *import* from the .ml file automatically". The thing I do find irritating maintaining .mli/.ml files is having to type anything out twice - and for the most part that means fully exported type declarations. Say you have a simple module:

Foo.mli (separate file, so the items can appear in a different order trivially)
=======

(** Foo. This module is an example *)

(** Annotation *)
type t = A (** Annotation *) | B (** Annotation *)

val bar : t -> bool
(** [bar x] returns true if [x] is [A] *)

Foo.ml
======

type t = A | B (* This duplication is annoying *)

let bar x = (x = A) (* No type declaration needed here *)

For me, "val bar" in the .mli and "let bar" in the .ml is not duplication as one is the implementation and the other is the exported type. However, I do find having to maintain type t in two files irritating (say if I want to add the constructor C) - especially if t has hundreds of constructors where you have to make sure the order is the same too, of course. What would be nice would be to be able to put this in the /.ml/ file: 

(** Annotation *)
type t = A (** Annotation *) | B (** Annotation *)

and then this in the /.mli/ file:

type t from implementation

or 

export type t

which would export the entire declaration and also its ocamldoc comments. For an opaque type, you have different declarations anyway, so just write them. The same would be true of module types and so on.

Just my 2p!


David