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

[Romain Bardou <romain.bardou@inria.fr>]

I also used to believe the .mli file should be somehow included in the
.ml file. Now I don't.

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.

- Even without numbers it will be harder to get the big picture from a
module. An approach I like about this is Pascal units, with an interface
section and an implementation section, in the same file. But it does not
solve the duplication issue.

- You need a way to specify abstraction. For instance:
  * specify that a type should be exported as "type t" instead of "type
t = A | B";
  * specify that a type should be exported as "type t = private A | B"
instead of "type t = A | B";
  * specify that a value should be exported as "val f: t -> t" instead
of "val f: int -> int"
  * specify that a value should be exported as "val f: int -> t" instead
of "val f: 'a -> 'a"
Often, people who want automatic .mli generation do not use abstraction,
which is the main point of interfaces.

- Don't forget that you need to take into account the whole OCaml
language, including objects, modules, polymorphic variants… It may be
more work than expected. And this project will need to be maintained and
follow the changes to the language.

Cheers,

-- 
Romain

Le 31/05/2013 08:26, Francois Berenger a écrit :
> On 05/31/2013 02:31 PM, Malcolm Matalka wrote:
>> I know of no such tool, but in counter to your premise: I used to think
>> maintaining a .ml and .mli was foolish, however I no longer do.
> 
> It itches me and it won't stop.
> 
>>  .mli is
>> effectively documentation for me.  It contains a lot of comments and is
>> generally written to reflect how the API should be used rather than the
>> order in which I must express functions to get ta .ml to compile.
> 
> I'm proposing to add some number to tags so that things can
> be reordered when dumped to the .mli.
> 
>>  On
>> top of that, ocamlc will fail to compile if your .ml and .mli don't
>> match,
> 
> The tool I am thinking about is a preprocessor.
> It would be used to generate all .mli files before the compilation
> of the .ml ones (at least in _MY_ OCaml projects).
> 
>> so it's a valuable check that what I think my module does is also
>> what the compiler does.  I also tend to write the .mli first, then write
>> the .ml.  I find it to be a great way to develop.
> 
> I don't.
> 
>> In short, I think it's a good thing to maintain these things by hand.
> 
> I don't:
> dumb_job + error_prone + can_be_automated + duplication_of_information
> --> the computer will do it for me.
> 
> I'm thinking about something small.
> It may not work on all cases people can come up with.
> I don't do very elaborated things usually so it will work for me,
> at least.
> 
>> But as for your original question I'm completely useless, sorry.
>>
>> /M
>>
>> Francois Berenger <berenger@riken.jp> writes:
>>
>>> Hello,
>>>
>>> Is there some recommended tool/script to generate a .mli
>>> from the corresponding .ml?
>>>
>>> I want a little more than ocamlc -i:
>>>
>>> - I think there should be tags in the .ml file as comments
>>>    that say "export this" to the .mli.
>>>    By default, things are not exported.
>>> - maybe it should have an option to say to replicate
>>>    the ocamldoc comments in the .mli.
>>> - it could be nice if the order in which things are exported
>>>    to the .mli can be specified, maybe as an argument of the tag.
>>>    So that the .mli can be more readable (only backward references
>>>    to concepts, etc.)
>>>
>>> If there is a need to create a tool, let's call it "nomli". :)
>>>
>>> Regards,
>>> F.
>>>
>>> PS: I'm not going to maintain both a .mli and a .ml.
>>>      I feel it is a dumb and error-prone job and that
>>>      itches me.
>>
> 
>