[LLVMdev] request for tutorial

[David Chisnall]

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