On 25 September 2013 22:13, Preston Briggs <preston.briggs at gmail.com> wrote:> 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. >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. 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. 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. cheers, --renato -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.llvm.org/pipermail/llvm-dev/attachments/20130925/4aabd123/attachment.html>
On 25 Sep 2013, at 22:22, Renato Golin <renato.golin at linaro.org> wrote:> 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. > > 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.This is especially true in the back end. For example, MCInstrDesc[1] completely lacks any class-level doc comment saying how you would map from an instruction to the description. It turns out that each back end exposes an array of MCInstrDesc objects, indexed by opcode (in the MCInstr sense, not in the target instruction set sense), but the only way to discover this is by grepping the codebase. We're generally quite good at adding comments on individual methods (or at making the method names self-explanatory), but not at documenting classes. I'd encourage anyone who has added a class to LLVM to revisit it and see if they can improve the documentation. Another example is object::ObjectFile. You can cast<> or dyn_cast<> these down to object::COFFObjectFiles or object::MachOObjectFiles easily, but object::ELFObjectFile is a template class and there's no documentation of what the template parameter should be, of it if's possible to infer it from the object::ObjectFile somehow. David Who has spent the last week writing a tool that uses the MC layer and found the lack of documentation frustrating [1] http://llvm.org/doxygen/classllvm_1_1MCInstrDesc.html
On 26 September 2013 10:03, David Chisnall <David.Chisnall at cl.cam.ac.uk>wrote:> Another example is object::ObjectFile. You can cast<> or dyn_cast<> these > down to object::COFFObjectFiles or object::MachOObjectFiles easily, but > object::ELFObjectFile is a template class and there's no documentation of > what the template parameter should be, of it if's possible to infer it from > the object::ObjectFile somehow. >This strikes me as poor design, helped by the fact that there was no expected API or documentation on how to use it, so special implementations will differ and become incompatible with each other. Per se, it's not a problem, but when you change the interface, (or when trying to use polymorphism), things can go wrong in mysterious ways. A few lines of comments saying what's expected from the derived classes would have prompted folks to work around the template problems (or found a different solution) before it became an issue. cheers, --renato -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.llvm.org/pipermail/llvm-dev/attachments/20130926/4007db42/attachment.html>
I think y'all underestimate how important documentation can be. 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. 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." Preston On Wed, Sep 25, 2013 at 2:22 PM, Renato Golin <renato.golin at linaro.org>wrote:> On 25 September 2013 22:13, Preston Briggs <preston.briggs at gmail.com>wrote: > >> 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. >> > > 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. > > 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. > > 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. > > cheers, > --renato >-------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.llvm.org/pipermail/llvm-dev/attachments/20130926/827f75d3/attachment.html>
On Thu, Sep 26, 2013 at 12:22 PM, Preston Briggs <preston.briggs at gmail.com>wrote:> I think y'all underestimate how important documentation can be. >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!) 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. 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.> 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. >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...> 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." > > Preston > > > > > On Wed, Sep 25, 2013 at 2:22 PM, Renato Golin <renato.golin at linaro.org>wrote: > >> On 25 September 2013 22:13, Preston Briggs <preston.briggs at gmail.com>wrote: >> >>> 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. >>> >> >> 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. >> >> 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. >> >> 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. >> >> cheers, >> --renato >> > >-------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.llvm.org/pipermail/llvm-dev/attachments/20130926/0aebfd0b/attachment.html>