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
No comments:
Post a Comment