Re: [Caml-list] Ocaml compiler documentation

[Mark Shinwell <mshinwell@janestreet.com>]

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 <yotambarnoy@gmail.com> 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-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ć <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 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 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, 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
>
>