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 DC5B57F89E for ; Mon, 31 Mar 2014 19:52:07 +0200 (CEST) Received-SPF: None (mail3-smtp-sop.national.inria.fr: no sender authenticity information available from domain of yotambarnoy@gmail.com) identity=pra; client-ip=209.85.192.50; receiver=mail3-smtp-sop.national.inria.fr; envelope-from="yotambarnoy@gmail.com"; x-sender="yotambarnoy@gmail.com"; x-conformance=sidf_compatible Received-SPF: Pass (mail3-smtp-sop.national.inria.fr: domain of yotambarnoy@gmail.com designates 209.85.192.50 as permitted sender) identity=mailfrom; client-ip=209.85.192.50; receiver=mail3-smtp-sop.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 (mail3-smtp-sop.national.inria.fr: no sender authenticity information available from domain of postmaster@mail-qg0-f50.google.com) identity=helo; client-ip=209.85.192.50; receiver=mail3-smtp-sop.national.inria.fr; envelope-from="yotambarnoy@gmail.com"; x-sender="postmaster@mail-qg0-f50.google.com"; x-conformance=sidf_compatible X-IronPort-Anti-Spam-Filtered: true X-IronPort-Anti-Spam-Result: AqMBABGqOVPRVcAylGdsb2JhbABZg0FXgwrAEoEYCBYOAQEBAQcLCwkSKoIlAQEBAwEjHQEbDwIMAQMBCwYFCw0qAgIhAQERAQUBHAYTCIdcAQMJCA2iO4wOUYMOllsKGScNZIV7EQEBBAyMV4IYBAeCb4FJBJZhgW2Ma4NbGCmEeiE X-IPAS-Result: AqMBABGqOVPRVcAylGdsb2JhbABZg0FXgwrAEoEYCBYOAQEBAQcLCwkSKoIlAQEBAwEjHQEbDwIMAQMBCwYFCw0qAgIhAQERAQUBHAYTCIdcAQMJCA2iO4wOUYMOllsKGScNZIV7EQEBBAyMV4IYBAeCb4FJBJZhgW2Ma4NbGCmEeiE X-IronPort-AV: E=Sophos;i="4.97,766,1389740400"; d="scan'208";a="54918130" Received: from mail-qg0-f50.google.com ([209.85.192.50]) by mail3-smtp-sop.national.inria.fr with ESMTP/TLS/RC4-SHA; 31 Mar 2014 19:52:06 +0200 Received: by mail-qg0-f50.google.com with SMTP id q108so7857771qgd.9 for ; Mon, 31 Mar 2014 10:52:05 -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 :cc:content-type; bh=jUF1j+Dl90lDJccLxX8rSGzyDJjifgw7PAFSGINFGBs=; b=U1RjaXVmF1Hd0HlM80UQIEZ2MtRJVTfN31LMpOymkln4nORaYywzPx7/b3/kcE3I+i xeRq20+ro7Z3Fj3d7ffF0KXZd1tA6tc+WBXLdLp47FJwsiUBr40uExFpQXBK8roTJkRz B1SqRjxoktI2kcUwFkkBN1zfuGAnRMi/R1I0BY6sVFSNzrXiJvLfRDSyt/5t+jURCDqR zEKBZA744KgkqWNmfMypUdLqHQn31xNa7hWUIxJ5ZTa0VZ95kVMRpPhvBVvWR69rt4NQ BmOpkzEUA7HFhxDSDdr8F1H2sjI1cAKL2FLiS0CuipoV2cwVdadS2eKi/WwAdyi+j7wW qv4w== X-Received: by 10.224.92.75 with SMTP id q11mr10378986qam.56.1396288325274; Mon, 31 Mar 2014 10:52:05 -0700 (PDT) MIME-Version: 1.0 Received: by 10.224.168.72 with HTTP; Mon, 31 Mar 2014 10:51:45 -0700 (PDT) In-Reply-To: References: From: Yotam Barnoy Date: Mon, 31 Mar 2014 13:51:45 -0400 Message-ID: To: =?ISO-8859-2?Q?Milan_Stanojevi=E6?= Cc: Ocaml Mailing List Content-Type: multipart/alternative; boundary=089e01493f10a1cf7004f5eab57d Subject: Re: [Caml-list] Ocaml compiler documentation --089e01493f10a1cf7004f5eab57d Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: quoted-printable 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-internalswhich 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 = 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 enoug= h, > > others are missing some basic explanations. Some explanations are also > > spread out throughout the codebase, making it hard to know what somethi= ng > > means unless you've read another part of the codebase that relates to i= t. > > > > 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 aforemention= ed > > 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, but > 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 so= me > > 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 > --089e01493f10a1cf7004f5eab57d Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable
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. A= dditionally, there's the ocaml-internals wiki at https://github.com/ocamllabs/ocaml-inter= nals 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 te= am, as well as the other experts on this list.

-Yotam


O= n 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 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 <yotambarnoy@gmail.com> wrote:
> Hi everybody
>
> It's been mentioned before that the OCaml compiler's documenta= tion is
> somewhat lacking. I've been going over the compiler code gradually= (both the
> frontend and the backend) and while some parts are understandable enou= gh,
> others are missing some basic explanations. Some explanations are also=
> spread out throughout the codebase, making it hard to know what someth= ing
> means unless you've read another part of the codebase that relates= to it.
>
> Since the call to submit documentation commits has gone mostly unanswe= red,
> I'd like to suggest a method of making both my own progress throug= h 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 ti= me, I'll
> post newbie questions to the list about the code. Once I'm satisfi= ed that I
> have a good enough understanding, I'll add comments to the aforeme= ntioned
> 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<= br> > members (who already know the compiler code) is the willingness to exp= lain
> 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 process -- I= 9;m doing this
> on the side while working on a research project and TAing, but I reall= y
> would like to get to the point where I can make significant contributi= ons to
> the toolchain, and if I can help others who follow in my footsteps, th= en
> 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 answe= r my
> questions even if they get annoying. In particular, I may often miss s= ome
> parts that may seem obvious because I don't necessarily have the t= ime to
> read all the connected code in depth. Hopefully you'll bear with m= e.
>
> Does this sound reasonable to the fine folks on the list?
>
> Yotam

--089e01493f10a1cf7004f5eab57d--