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ć <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
>