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