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 mail2-relais-roc.national.inria.fr (mail2-relais-roc.national.inria.fr [192.134.164.83]) by sympa.inria.fr (Postfix) with ESMTPS id 859197F89E for ; Thu, 3 Apr 2014 04:48:26 +0200 (CEST) Received-SPF: None (mail2-smtp-roc.national.inria.fr: no sender authenticity information available from domain of yotambarnoy@gmail.com) identity=pra; client-ip=209.85.192.42; receiver=mail2-smtp-roc.national.inria.fr; envelope-from="yotambarnoy@gmail.com"; x-sender="yotambarnoy@gmail.com"; x-conformance=sidf_compatible Received-SPF: Pass (mail2-smtp-roc.national.inria.fr: domain of yotambarnoy@gmail.com designates 209.85.192.42 as permitted sender) identity=mailfrom; client-ip=209.85.192.42; receiver=mail2-smtp-roc.national.inria.fr; envelope-from="yotambarnoy@gmail.com"; x-sender="yotambarnoy@gmail.com"; x-conformance=sidf_compatible; x-record-type="v=spf1" Received-SPF: None (mail2-smtp-roc.national.inria.fr: no sender authenticity information available from domain of postmaster@mail-qg0-f42.google.com) identity=helo; client-ip=209.85.192.42; receiver=mail2-smtp-roc.national.inria.fr; envelope-from="yotambarnoy@gmail.com"; x-sender="postmaster@mail-qg0-f42.google.com"; x-conformance=sidf_compatible X-IronPort-Anti-Spam-Filtered: true X-IronPort-Anti-Spam-Result: AmUEAInKPFPRVcAqeGdsb2JhbABZg0FXgwrAYIEVCBYOARUmKoIlAQEBAwEjHQEbDwINAwELBgMCCw0qAgIhAQERAQUBHAYTh2QBAwkIDZEpkAqMDlGDDpYzChknDWSGUhEBAQQMjEqCFguCb4FJBJQogkOBbYxtg10YKYR6IQ X-IPAS-Result: AmUEAInKPFPRVcAqeGdsb2JhbABZg0FXgwrAYIEVCBYOARUmKoIlAQEBAwEjHQEbDwINAwELBgMCCw0qAgIhAQERAQUBHAYTh2QBAwkIDZEpkAqMDlGDDpYzChknDWSGUhEBAQQMjEqCFguCb4FJBJQogkOBbYxtg10YKYR6IQ X-IronPort-AV: E=Sophos;i="4.97,783,1389740400"; d="scan'208";a="66126947" Received: from mail-qg0-f42.google.com ([209.85.192.42]) by mail2-smtp-roc.national.inria.fr with ESMTP/TLS/RC4-SHA; 03 Apr 2014 04:48:25 +0200 Received: by mail-qg0-f42.google.com with SMTP id q107so1175721qgd.29 for ; Wed, 02 Apr 2014 19:48:24 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=mime-version:in-reply-to:references:from:date:message-id:subject:to :content-type; bh=xSdcjPDunNdM+FRykBP5pYGqlZJo8+1LYs+Y4zEHwTs=; b=LFRBa5cdctxPQSd/Ovgz/mMUAVLUerLyqzkkh5xz5WbzZILxhqnKboJl+IwO/S81qM /IOd2OHBFYnXf/HJW0DZ/uYKX/r3eWcPNi2Me5sIh7BgeuklyGs1dII+TMGqqpAM91gU kzM4yQnnsCj9n4S7AAyb6BkD1sIIxNFesjbqjXp8bb9ReNgUPW0Q9Nc8OKyoZyNwkyxU zUoVuC2rPaefOKD8SMvTUznqOpdDJW8LBO5xSg0TmAZfs4gClLtAQycBCJp3U6tpimqx EpvUNDpdBPbXQAaFDB4wdvFGW4lLRVjSa8RI4H1mkPo+6cy6fRsvEqQ6DAA0hGMGClST lOIA== X-Received: by 10.140.87.5 with SMTP id q5mr4393641qgd.31.1396493304055; Wed, 02 Apr 2014 19:48:24 -0700 (PDT) MIME-Version: 1.0 Received: by 10.224.168.72 with HTTP; Wed, 2 Apr 2014 19:48:03 -0700 (PDT) In-Reply-To: References: From: Yotam Barnoy Date: Wed, 2 Apr 2014 22:48:03 -0400 Message-ID: To: Ocaml Mailing List Content-Type: multipart/alternative; boundary=001a113ab2ec51ce1f04f61a6f79 Subject: Re: [Caml-list] Ocaml compiler documentation --001a113ab2ec51ce1f04f61a6f79 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: quoted-printable 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. 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. Since the file is so well documented, I only have a few questions. I'll accept an answer or a hunch from anyone -- don't feel shy because you think you're not sure about the answer: 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? 2. What is demonstrated in lines 114-117 regarding polymorphic variant row fields: | Rtag of label * bool * core_type list (* [`A] ( true, [] ) [`A of T] ( false, [T] ) [`A of T1 & .. & Tn] ( false, [T1;...Tn] ) [`A of & T1 & .. & Tn] ( true, [T1;...Tn] ) *) What does the bool value represent? Why are the type separators in the comments using the & symbol? What is the difference between the 3rd and 4th example? 3. line 684: what is the purpose of the override flag on Pstr_open? It's not explained by the comment. 4. The toplevel phrases are not clear. What is the purpose of Ptop_dir on line 721? Like I said, feel free to jump in and answer any one of these questions. Thanks in advance for everyone's help -Yotam On Tue, Apr 1, 2014 at 6:03 AM, Mark Shinwell wro= te: > I would suggest that it's probably better to keep the documentation as > comments where possible. However, I think it is important to avoid > excessive commentary, especially if it is likely to get out of sync as > a result of future modifications to the code. It may be that in some > cases making alterations to the code (for example, improving the name > of a variable) is a more satisfactory approach than adding a comment. > > Thanks for working on this. > > Mark > > On 31 March 2014 18:51, Yotam Barnoy wrote: > > I think it depends on how much feedback I get on any particular > question. By > > default, I would like comments to go in the code. Additionally, there's > the > > ocaml-internals wiki at https://github.com/ocamllabs/ocaml-internalswhi= ch > > will be useful for any concepts that span multiple files, or that are t= oo > > beginner-oriented. I'm guessing that for many things, it will just have > to > > be decided on a case-by-case basis. > > > > Of course, the most important ingredient for the success of this > 'project' > > is the willing, patient participation of the core team, as well as the > other > > experts on this list. > > > > -Yotam > > > > > > On Mon, Mar 31, 2014 at 1:06 PM, Milan Stanojevi=C4=87 > wrote: > >> > >> Thank you for doing this, I'm interested in learning more about how > >> compiler works. > >> > >> Are you creating a separate file(s) to document the compiler or you > >> are adding comments to ml files? > >> > >> On Mon, Mar 31, 2014 at 11:39 AM, Yotam Barnoy > >> wrote: > >> > Hi everybody > >> > > >> > It's been mentioned before that the OCaml compiler's documentation is > >> > somewhat lacking. I've been going over the compiler code gradually > (both > >> > the > >> > frontend and the backend) and while some parts are understandable > >> > enough, > >> > others are missing some basic explanations. Some explanations are al= so > >> > spread out throughout the codebase, making it hard to know what > >> > something > >> > means unless you've read another part of the codebase that relates to > >> > it. > >> > > >> > Since the call to submit documentation commits has gone mostly > >> > unanswered, > >> > I'd like to suggest a method of making both my own progress through > the > >> > code > >> > easier and hopefully making it easier for others who will follow. > >> > > >> > What I'm going to do is, focusing on more or less one file at a time, > >> > I'll > >> > post newbie questions to the list about the code. Once I'm satisfied > >> > that I > >> > have a good enough understanding, I'll add comments to the > >> > aforementioned > >> > files and submit pull requests for them. I also encourage others to = do > >> > the > >> > same. > >> > > >> > What I need from the list, and especially from the more knowledgeable > >> > members (who already know the compiler code) is the willingness to > >> > explain > >> > the concepts and answer my questions, annoying as they may be. I have > a > >> > pretty decent background in compilers, ASTs, code generation, etc, b= ut > >> > not > >> > so much in type inference. > >> > > >> > I'm not suggesting a particular timeframe for this process -- I'm > doing > >> > this > >> > on the side while working on a research project and TAing, but I > really > >> > would like to get to the point where I can make significant > >> > contributions to > >> > the toolchain, and if I can help others who follow in my footsteps, > then > >> > that's a nice bonus. > >> > > >> > While I could have skipped this introduction and just proceeded with > >> > inundating the list with questions, I felt that this (hopefully) > gives a > >> > purpose and perhaps motivation for those who have the answers to > answer > >> > my > >> > questions even if they get annoying. In particular, I may often miss > >> > some > >> > parts that may seem obvious because I don't necessarily have the time > to > >> > read all the connected code in depth. Hopefully you'll bear with me. > >> > > >> > Does this sound reasonable to the fine folks on the list? > >> > > >> > Yotam > > > > > --001a113ab2ec51ce1f04f61a6f79 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable
Ok I think a good place to start a tour of the compil= er is in parsing/parsetree.mli. This file is actually very well documented,= with terse but effective examples of almost every constructor and type.

I had to refer to the OCaml manual for a few of the corner cases. For e= xample, I didn't know about the #class type shortcut. I think a few com= ments explaining the more obscure facets of the language could be helpful.<= br>
Since the file is so well documented, I only have a few questions. I= 9;ll accept an answer or a hunch from anyone -- don't feel shy because = you think you're not sure about the answer:

1. What is the diffe= rence between an extension and an attribute? From what I understand, they a= re 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 mechan= isms?

2. What is demonstrated in lines 114-117 regarding polymorphic variant = row fields:

=C2=A0 | Rtag of label * bool * core_type list
=C2=A0= =C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 (* [`A]=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0= =C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2= =A0 ( true,=C2=A0 [] )
=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0= =C2=A0=C2=A0 [`A of T]=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2= =A0=C2=A0=C2=A0=C2=A0=C2=A0 ( false, [T] )
=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 [`A of T1 &= ; .. & Tn]=C2=A0=C2=A0 ( false, [T1;...Tn] )
=C2=A0=C2=A0=C2=A0=C2= =A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 [`A of & T1 & .. & Tn] = ( true,=C2=A0 [T1;...Tn] )
=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2= =A0 *)

What does the bool value represent?
Why are the type sepa= rators in the comments using the & symbol?
What is the difference between the 3rd and 4th example?

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

4. The toplevel phrases are not clear. What is t= he purpose of Ptop_dir on line 721?

Like I said, feel free to jump in and answer any one of these questions= .

Thanks in advance for everyone's help

=
-Yotam




On Tue, Apr 1, 2014 at 6:03 AM, Mark Shi= nwell <mshinwell@janestreet.com> wrote:
I would suggest that it's probably better to keep the documentation as<= br> comments where possible. =C2=A0However, I think it is important to avoid
excessive commentary, especially if it is likely to get out of sync as
a result of future modifications to the code. =C2=A0It may be that in some<= br> cases making alterations to the code (for example, improving the name
of a variable) is a more satisfactory approach than adding a comment.

Thanks for working on this.

Mark

On 31 March 2014 18:51, Yotam Barnoy <yotambarnoy@gmail.com> wrote:
> I think it depends on how much feedback I get on any particular questi= on. By
> default, I would like comments to go in the code. Additionally, there&= #39;s the
> ocaml-internals wiki at https://github.com/ocamllabs/ocaml-internals which
> will be useful for any concepts that span multiple files, or that are = too
> beginner-oriented. I'm guessing that for many things, it will just= have to
> be decided on a case-by-case basis.
>
> Of course, the most important ingredient for the success of this '= project'
> is the willing, patient participation of the core team, as well as the= other
> experts on this list.
>
> -Yotam
>
>
> On Mon, Mar 31, 2014 at 1:06 PM, Milan Stanojevi=C4=87 <milanst@gmail.com> wrote:
>>
>> Thank you for doing this, I'm interested in learning more abou= t how
>> compiler works.
>>
>> Are you creating a separate file(s) to document the compiler or yo= u
>> are adding comments to ml files?
>>
>> On Mon, Mar 31, 2014 at 11:39 AM, Yotam Barnoy <yotambarnoy@gmail.com>
>> wrote:
>> > Hi everybody
>> >
>> > It's been mentioned before that the OCaml compiler's = documentation is
>> > somewhat lacking. I've been going over the compiler code = gradually (both
>> > the
>> > frontend and the backend) and while some parts are understand= able
>> > enough,
>> > others are missing some basic explanations. Some explanations= are also
>> > spread out throughout the codebase, making it hard to know wh= at
>> > something
>> > means unless you've read another part of the codebase tha= t relates to
>> > it.
>> >
>> > Since the call to submit documentation commits has gone mostl= y
>> > unanswered,
>> > I'd like to suggest a method of making both my own progre= ss through the
>> > code
>> > easier and hopefully making it easier for others who will fol= low.
>> >
>> > What I'm going to do is, focusing on more or less one fil= e at a time,
>> > I'll
>> > post newbie questions to the list about the code. Once I'= m satisfied
>> > that I
>> > have a good enough understanding, I'll add comments to th= e
>> > aforementioned
>> > files and submit pull requests for them. I also encourage oth= ers to do
>> > the
>> > same.
>> >
>> > What I need from the list, and especially from the more knowl= edgeable
>> > members (who already know the compiler code) is the willingne= ss to
>> > explain
>> > the concepts and answer my questions, annoying as they may be= . I have a
>> > pretty decent background in compilers, ASTs, code generation,= etc, but
>> > not
>> > so much in type inference.
>> >
>> > I'm not suggesting a particular timeframe for this proces= s -- I'm doing
>> > this
>> > on the side while working on a research project and TAing, bu= t I really
>> > would like to get to the point where I can make significant >> > contributions to
>> > the toolchain, and if I can help others who follow in my foot= steps, then
>> > that's a nice bonus.
>> >
>> > While I could have skipped this introduction and just proceed= ed with
>> > inundating the list with questions, I felt that this (hopeful= ly) gives a
>> > purpose and perhaps motivation for those who have the answers= to answer
>> > my
>> > questions even if they get annoying. In particular, I may oft= en miss
>> > some
>> > parts that may seem obvious because I don't necessarily h= ave the time to
>> > read all the connected code in depth. Hopefully you'll be= ar with me.
>> >
>> > Does this sound reasonable to the fine folks on the list?
>> >
>> > Yotam
>
>

--001a113ab2ec51ce1f04f61a6f79--