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

[Francois Berenger <berenger@riken.jp>]

On 06/04/2013 02:12 AM, Alain Frisch wrote:
> I've created a proof-of-concept implementation of such a tool as part of
> the "extension_points" branch, which introduces a syntax for attributes
> on various syntactic items (including type declarations and value
> bindings).
>
> Note that I *don't* endorse the idea of generating .mli files
> automatically :-)
>
> Here is the code:
>
> http://caml.inria.fr/cgi-bin/viewvc.cgi/ocaml/branches/extension_points/experimental/frisch/nomli.ml?revision=HEAD&view=markup
>
> and an example:
>
> http://caml.inria.fr/cgi-bin/viewvc.cgi/ocaml/branches/extension_points/experimental/frisch/test_nomli.ml?revision=HEAD&view=markup

Alain, I am amazed!

Would it be possible to handle the two following things?

- being able to assign priorities to things exported in the
   .mli file (to re-order the .mli in some way that makes it easier to
   grasp). I think floats should be used and the priority assigned
   should be shown in the .mli so that users can quickly see what
   priority they need to change in the .ml to obtain the order
   they want in the .mli

- can you also handle the transfer of ocamldoc comments in the .ml
   to the .mli (I read later that you also have a final solution
   for ocamldoc too)?

The tool I was thinking of would not do anything more...

> On 05/31/2013 05:43 AM, Francois Berenger wrote:
>> - I think there should be tags in the .ml file as comments
>>    that say "export this" to the .mli.
>
> Encoding annotations in comments is very fragile, because they are not
> kept by the parser in the generated Parsetree, and it is not
> well-defined to which component each component refers to.  ocamldoc uses
> comments, and as a consequence, it does not combine well with
> preprocessors (Camlp4/Camlp5/Fan/ppx extensions cannot generate
> documentation fragments, and it is likely that they break existing
> ones).  A version of ocamldoc based on attributes of the
> extension_points branch would be much more robust (and simple).

The same is true for qtest I guess.

>  I've
> written another toy POC implementation of a mini-ocamldoc based on
> attributes:
>
> http://caml.inria.fr/cgi-bin/viewvc.cgi/ocaml/branches/extension_points/experimental/frisch/minidoc.ml?revision=HEAD&view=markup
>
> http://caml.inria.fr/cgi-bin/viewvc.cgi/ocaml/branches/extension_points/experimental/frisch/testdoc.mli?revision=HEAD&view=markup

Thanks a lot for the code and explanations.

Best regards,
Francois.