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 43B1F7F89E for ; Tue, 1 Apr 2014 12:03:30 +0200 (CEST) Received-SPF: None (mail3-smtp-sop.national.inria.fr: no sender authenticity information available from domain of mshinwell@janestreet.com) identity=pra; client-ip=38.105.200.229; receiver=mail3-smtp-sop.national.inria.fr; envelope-from="mshinwell@janestreet.com"; x-sender="mshinwell@janestreet.com"; x-conformance=sidf_compatible Received-SPF: Pass (mail3-smtp-sop.national.inria.fr: domain of mshinwell@janestreet.com designates 38.105.200.229 as permitted sender) identity=mailfrom; client-ip=38.105.200.229; receiver=mail3-smtp-sop.national.inria.fr; envelope-from="mshinwell@janestreet.com"; x-sender="mshinwell@janestreet.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@mx5.mail.janestreet.com) identity=helo; client-ip=38.105.200.229; receiver=mail3-smtp-sop.national.inria.fr; envelope-from="mshinwell@janestreet.com"; x-sender="postmaster@mx5.mail.janestreet.com"; x-conformance=sidf_compatible X-IronPort-Anti-Spam-Filtered: true X-IronPort-Anti-Spam-Result: AuABAFqOOlMmacjlnGdsb2JhbABZg0FXgwrAJYETHg4BAQEBAQYWCTyCJQEBAQQjHQEBKQIMAQ8LCw0CAiYCAiEBEgEFARwGE4dlAxEDAgiiWYsYdoNfAQWXHw2HSxECBIEpiy2BZzMHgm+BSZQqgkOBbYxtg10YKYRf X-IPAS-Result: AuABAFqOOlMmacjlnGdsb2JhbABZg0FXgwrAJYETHg4BAQEBAQYWCTyCJQEBAQQjHQEBKQIMAQ8LCw0CAiYCAiEBEgEFARwGE4dlAxEDAgiiWYsYdoNfAQWXHw2HSxECBIEpiy2BZzMHgm+BSZQqgkOBbYxtg10YKYRf X-IronPort-AV: E=Sophos;i="4.97,771,1389740400"; d="scan'208";a="55041215" Received: from mx5.janestreet.com (HELO mx5.mail.janestreet.com) ([38.105.200.229]) by mail3-smtp-sop.national.inria.fr with ESMTP/TLS/DHE-RSA-AES256-SHA; 01 Apr 2014 12:03:29 +0200 Received: from tot-oib-smtp1.delacy.com ([172.27.22.15] helo=tot-smtp) by mx5.mail.janestreet.com with esmtp (Exim 4.76) (envelope-from ) id 1WUvXR-0002k8-UE for caml-list@inria.fr; Tue, 01 Apr 2014 06:03:25 -0400 Received: from tot-dmz-mxgoog1.delacy.com ([172.27.224.14] helo=mxgoog2.janestreet.com) by tot-smtp with esmtps (TLSv1:AES256-SHA:256) (Exim 4.72) (envelope-from ) id 1WUvXR-00028X-TH for caml-list@inria.fr; Tue, 01 Apr 2014 06:03:25 -0400 Received: from mail-pd0-f182.google.com ([209.85.192.182]) by mxgoog2.janestreet.com with esmtp (Exim 4.76) (envelope-from ) id 1WUvXR-0003SW-PA for caml-list@inria.fr; Tue, 01 Apr 2014 06:03:25 -0400 Received: by mail-pd0-f182.google.com with SMTP id y10so9399669pdj.27 for ; Tue, 01 Apr 2014 03:03:25 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=janestreet.com; s=google; h=mime-version:in-reply-to:references:date:message-id:subject:from:to :cc:content-type:content-transfer-encoding; bh=Xe/Xr46MlNxQ5zjC9Bhe0q6mO/xpv4XFJfuHSXKJf/s=; b=aBhBnoPlBF5A1iZ8Td2wNJ8bMuB3z/WG48hI+7TK9dfA/QCBobhP9fjr+fwC49Mtkc glkCGzh6V9uxXYq367P1MOzf0P6fK1IIq+9zgjmFqC1l25e5sWvXLIU8yWeIOI4JyKMg nEvYONskvUeNErJySUEGGwAK5DjYEInYfW51M= X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:mime-version:in-reply-to:references:date :message-id:subject:from:to:cc:content-type :content-transfer-encoding; bh=Xe/Xr46MlNxQ5zjC9Bhe0q6mO/xpv4XFJfuHSXKJf/s=; b=CEUMrSXavi9fVbLtB7sGDmQedeX/SFzcNFtKWnJVpC0v8nTPp6H2+onPL9/01avi45 CsfQXbWdZGiw9x5Hz/NnLVUweaPhIqzg1XExIFmh8dwRDLU3CkFxDEmM+c7x/8s5Fz75 PgPQW0Ox1724Q7VynDd/u9n76X8HG937YdF2Kjp4h8vndXJ8OS0LHGv+OFUsFBl1HyAe UvVvxK0eNxZlGc5xSNsTocUBQPpDowd+A5AI8ChsOnZFDbgICu9Opl93mUS5SwSmUvwE 0P1H+p1SS4GwQ3TrUVjP6ghCNfjUFwUJ+9bHquNI/SNdBZWQLOqfsP1EPZli3bKrgGe3 vP+A== X-Gm-Message-State: ALoCoQkSJkkByhaQ8WCWvsdK4BBMdsgKMqZrx9/jwZ9F6lY6CqZWySJu4qrU7zkClXtO+06w9SVwZKvU5cT4DjvUAPNr0ZVXD1keKuR8S6Bsc3Kt85/iDIT6/BchMxLY7AQtbgxzyxXOq/4AKkCusIsVeVxy1U6ZLg== X-Received: by 10.66.139.70 with SMTP id qw6mr13986314pab.111.1396346605249; Tue, 01 Apr 2014 03:03:25 -0700 (PDT) MIME-Version: 1.0 X-Received: by 10.66.139.70 with SMTP id qw6mr13986298pab.111.1396346605127; Tue, 01 Apr 2014 03:03:25 -0700 (PDT) Received: by 10.70.74.134 with HTTP; Tue, 1 Apr 2014 03:03:25 -0700 (PDT) In-Reply-To: References: Date: Tue, 1 Apr 2014 11:03:25 +0100 Message-ID: From: Mark Shinwell To: Yotam Barnoy Cc: =?ISO-8859-2?Q?Milan_Stanojevi=E6?= , Ocaml Mailing List Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: quoted-printable X-Validation-by: mshinwell@janestreet.com Subject: Re: [Caml-list] Ocaml compiler documentation 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 t= he > 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 ot= her > 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 (bo= th >> > the >> > frontend and the backend) and while some parts are understandable >> > enough, >> > others are missing some basic explanations. Some explanations are also >> > 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, 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, 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 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 > >