Re: autogeneration of *.mli files

[Julian Assange <proff@iq.org>]

Thanks for all your comments on this issue. I'll try and respond more
tomorrow, but for now here's a quick summary of my thoughts:

        o The current mli situation is not nearly as bad as I was
          previously led to believe.

        o I didn't know about ocaml -c -i

        o I didn't know that symbols could be accessed safely from differing
          *.ml files, without writing an *.mli interface

        o While I'm only relatively new to ocaml, the fact that I
          didn't know these two implementation points, yet feel
          reasonably comfortable with the language proper shows a
          weakness in the documentation.
          
        o There is a need for a a tutorial (in English) on the
          interaction of ocaml tools, symbols and program
          structure. Something like `Creating non-trivial software
          projects with Ocaml'. Which takes one through:

                o how to call the compiler
                o using OcamlMakefile and other build tools
                o when and where to use seperate .ml files
                o name space issues
                o encapsulation and modularisation of functions and types
                o in what circumstances one should write .mli files
                o calling ocaml -c -i
                o linking in external libraries
                o objects vs modules
                o when to use the debugger
                o example design-compile-edit-debug-optimise cycles that
                  work for experienced O'caml coders.

        Hopefully the Oreilly book will address some of this.

        o If one doesn't use *.mli files, are there issues of name-space polution?
          Does using a mli interface actually prevent exports of symbols not
          defined in the interface?

        o While ocaml -c -i exports types, I presume it doesn't export
          comments, and that it exports many more types than you would
          normally want in your .mli interface? Even a flag to export
          the immediately preceding comment would be useful.

        o While a number of people talked about writing *.mli's by
          hand for design purposes, it seems to me me that the vast majority
          of mli's have their genesis from ocaml -c -i.

        o To examine the behavior of type inference, I often send code fragments
          to the top-level. It would be nice to a version of ocaml -c -i which
          `annotated' ml code in context, either as type decelerations or commented
          out type declerations, rather than just spitting out the types on their
          own. This would improve program readability without sacrificing the
          benefits of type inference. Doesn't efuns do something like this?

        o For those people who really do write to .mli specs, how about the
          reverse, annotation of .ml files based on comments and types in
          the corresponding .mli?

        o Reading unfamiliar ocaml code that has no comments or type
          annotations is usually substantially harder than code that has
          them. Cut and pasting comments and or type declarations to and
          from mli and ml files strikes me as a waste of human
          intelligence. Obviously others feel the same way, which is mli
          files are often out of sync with correspinding ml files.

Cheers,
Julian.