Re: [Caml-list] Ocaml compiler documentation

[Alain Frisch <alain@frisch.fr>]

On 4/3/2014 4:48 AM, Yotam Barnoy wrote:
> Ok I think a good place to start a tour of the compiler is in
> parsing/parsetree.mli. This file is actually very well documented, with
> terse but effective examples of almost every constructor and type.

Good idea indeed, especially that the Parsetree will gain in the next 
release a more important status, with -ppx rewriters, annotations and 
attributes.

> I had to refer to the OCaml manual for a few of the corner cases. For
> example, I didn't know about the #class type shortcut. I think a few
> comments explaining the more obscure facets of the language could be
> helpful.

Generally speaking, a good place to document the language is the user 
manual.  Don't hesitate to suggest patches to the manual as well!  (The 
source code is in the same repository: 
http://caml.inria.fr/cgi-bin/viewvc.cgi/ocamldoc/trunk/ ).

That said, for the specific case of Parsetree, it might indeed be useful 
to give some hints about rare language features in the source code as well.

> 1. What is the difference between an extension and an attribute? From
> what I understand, they are both means of integrating additional
> metadata into the AST that can then be parsed by implementations of the
> ast-mapper, but why are there 2 mechanisms?

An extension is something which will be rejected by the type-checker. 
It is placeholder for "sub-languages", to be processed by -ppx filters.

An attribute is indeed a way to integrate meta-data into a (hopefully) 
valid AST.  They could be used by -ppx filters to drive their behavior, 
by external tools to get some extra information (e.g. Bisect 
annotations), and they are propagated to the typedtreed, and hence to 
.cmt/.cmti files, again for external tools which read those files.  They 
are also kepts on some kinds of declarations (e.g. values and types) so 
that they are part of the Types structures, and hence found in .cmi 
files as well.  The compiler also give a built-in meaning to some 
attributes (to be documented).

Some more information: 
http://caml.inria.fr/cgi-bin/viewvc.cgi/ocaml/trunk/experimental/frisch/extension_points.txt?revision=HEAD&view=markup

> 3. line 684: what is the purpose of the override flag on Pstr_open? It's
> not explained by the comment.

The override flag (i.e. "open!" as opposed to "open") is used to silence 
the new warning which signals when an open statement shadows an existing 
identifier which is later used.   (It does not affect the 'unused open' 
warning.)

> 4. The toplevel phrases are not clear. What is the purpose of Ptop_dir
> on line 721?

Those are #-directives understood by the toplevel (#use, #load, etc).


-- Alain