From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Original-To: caml-list@sympa.inria.fr Delivered-To: caml-list@sympa.inria.fr Received: from mail3-relais-sop.national.inria.fr (mail3-relais-sop.national.inria.fr [192.134.164.104]) by sympa.inria.fr (Postfix) with ESMTPS id 2E0F57F89E for ; Thu, 3 Apr 2014 22:16:01 +0200 (CEST) Received-SPF: None (mail3-smtp-sop.national.inria.fr: no sender authenticity information available from domain of alain@frisch.fr) identity=pra; client-ip=80.12.242.128; receiver=mail3-smtp-sop.national.inria.fr; envelope-from="alain@frisch.fr"; x-sender="alain@frisch.fr"; x-conformance=sidf_compatible Received-SPF: None (mail3-smtp-sop.national.inria.fr: no sender authenticity information available from domain of alain@frisch.fr) identity=mailfrom; client-ip=80.12.242.128; receiver=mail3-smtp-sop.national.inria.fr; envelope-from="alain@frisch.fr"; x-sender="alain@frisch.fr"; x-conformance=sidf_compatible Received-SPF: None (mail3-smtp-sop.national.inria.fr: no sender authenticity information available from domain of postmaster@smtp.smtpout.orange.fr) identity=helo; client-ip=80.12.242.128; receiver=mail3-smtp-sop.national.inria.fr; envelope-from="alain@frisch.fr"; x-sender="postmaster@smtp.smtpout.orange.fr"; x-conformance=sidf_compatible X-IronPort-Anti-Spam-Filtered: true X-IronPort-Anti-Spam-Result: As0DAAfAPVNQDPKAeGdsb2JhbABYg0GDYcAhUYE2DgEVJiqCJQEBAQMBIxU0CgIGCwsYAgIFFgsCAgkDAgECAUUGAQwIAQGHbQwJrFSiYxeBKY1Pgm+BSQEDmFuBNIUdjx8 X-IPAS-Result: As0DAAfAPVNQDPKAeGdsb2JhbABYg0GDYcAhUYE2DgEVJiqCJQEBAQMBIxU0CgIGCwsYAgIFFgsCAgkDAgECAUUGAQwIAQGHbQwJrFSiYxeBKY1Pgm+BSQEDmFuBNIUdjx8 X-IronPort-AV: E=Sophos;i="4.97,790,1389740400"; d="scan'208";a="55464583" Received: from smtp06.smtpout.orange.fr (HELO smtp.smtpout.orange.fr) ([80.12.242.128]) by mail3-smtp-sop.national.inria.fr with ESMTP; 03 Apr 2014 22:16:00 +0200 Received: from [192.168.1.24] ([81.249.80.103]) by mwinf5d64 with ME id lYFz1n00M2DkosZ03YFzEh; Thu, 03 Apr 2014 22:15:59 +0200 Message-ID: <533DC189.5090206@frisch.fr> Date: Thu, 03 Apr 2014 22:16:09 +0200 From: Alain Frisch User-Agent: Mozilla/5.0 (Windows NT 6.1; WOW64; rv:24.0) Gecko/20100101 Thunderbird/24.4.0 MIME-Version: 1.0 To: Yotam Barnoy , Ocaml Mailing List References: In-Reply-To: Content-Type: text/plain; charset=UTF-8; format=flowed Content-Transfer-Encoding: 7bit Subject: Re: [Caml-list] Ocaml compiler documentation 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