<div dir="ltr"><br><div class="gmail_extra"><br><br><div class="gmail_quote">On Thu, Sep 26, 2013 at 12:22 PM, Preston Briggs <span dir="ltr"><<a href="mailto:preston.briggs@gmail.com" target="_blank">preston.briggs@gmail.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr">I think y'all underestimate how important documentation can be.</div></blockquote><div><br></div><div>
I'm a strong proponent for good documentation, and whenever I get a solid understanding of a specific part of LLVM I will usually write documentation for it. (I'm pretty clueless about backend stuff, which is why I haven't produced any documentation there!)</div>
<div><br></div><div>I think it's largely an issue with LLVM's culture. If somebody commits something without tests, they will rapidly receive code review feedback asking for tests; if someone adds a diagnostic to clang that has a really bad user experience, they will be flagged for it and asked to improve it.</div>
<div><br></div><div>On the other hand, if somebody commits something without documentation (or with poor documentation), usually I'm the only one that will flag them for it and ask them to improve it.</div><div> </div>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr">There are, after all, documents out there that purport to be guides to writing a back end for LLVM. I know of 2 other experienced & motivated compiler writers who read the available documentation, wrote some code, foundered, gave up, and wrote their own back end from scratch. So there's three of us that I know about, and I don't get around much.</div>
</blockquote><div><br></div><div>This makes me kind of depressed. I had always surmised that most of the reason that I had a hard time grokking the backend code was due to simply not having any formal compiler education (e.g. never taken a course or read a book about it), so last weekend I read Cooper & Torczon's "Engineering a Compiler" in an attempt to gain a better understanding of the subject. If you're having a hard time grokking the LLVM backend stuff (and you're the most cited author (excluding self-citations) in EaC), then I'm not sure what my prospects are...</div>
<div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr">A friend in the newspaper business said they had a rule of thumb that said approximately: "One letter from a reader implies another hundred readers out there who had the same opinion."<span class="HOEnZb"><font color="#888888"><div>

<br></div><div>Preston</div><div><br></div><div><br></div></font></span></div><div class="HOEnZb"><div class="h5"><div class="gmail_extra"><br><br><div class="gmail_quote">On Wed, Sep 25, 2013 at 2:22 PM, Renato Golin <span dir="ltr"><<a href="mailto:renato.golin@linaro.org" target="_blank">renato.golin@linaro.org</a>></span> wrote:<br>

<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr"><div>On 25 September 2013 22:13, Preston Briggs <span dir="ltr"><<a href="mailto:preston.briggs@gmail.com" target="_blank">preston.briggs@gmail.com</a>></span> wrote:<br>

</div><div class="gmail_extra"><div class="gmail_quote"><div>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr"><div> A lot of my difficulty in reading other examples is that it's not clear what matters and what doesn't. It's what I hope to get by sitting next to someone and asking questions. Some of this could be addressed in a guide. I'd start with a chapter on planning.</div>


</div></blockquote><div><br></div></div><div>Another approach, a mix between a dummy back end and Karen's proposal, is to not only write documents on how things piece together, but also add comments to the code on how important this file/function is, how it fits with the rest, and how generic/specific it is.</div>


<div><br></div><div>Documentations get outdated more often than comments in the code, and LLVM is particularly good at generic comments, but not so much at teaching how to use the code.</div><div><br></div><div>Patches adding comments are also a good way to learn how something works. You send a comment, people say how wrong that is, and in the end, you learn by teaching others via your comments.</div>


<div><br></div><div>cheers,</div><div>--renato</div></div></div></div>
</blockquote></div><br></div>
</div></div></blockquote></div><br></div></div>