[LLVMbugs] [Bug 20170] Typo of "allocation"

[bugzilla-daemon at llvm.org]

http://llvm.org/bugs/show_bug.cgi?id=20170

Sean Silva <chisophugis at gmail.com> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
             Status|REOPENED                    |RESOLVED
         Resolution|---                         |INVALID

--- Comment #6 from Sean Silva <chisophugis at gmail.com> ---
(In reply to comment #5)
> I didn't, so giving some hint to research it would have helped me understand.

Ok. At first it may seem like I'm simply being dismissive, but I'm going to
mark this as RESOLVED INVALID. I'm really not being dismissive; hopefully the
fairly lengthy explanation that follows will clarify this.


Every document has to make assumptions about what the reader knows (or can look
up). Actually, this is fundamental to any kind of communication.

In this case, the document assumes that the reader is familiar with LLVM IR;
this transitively means that you are familiar with LLVM's alloca instruction
since it is one of the most fundamental instructions, and therefore are
familiar with the concept of alloca. Also, any person that has been programming
in C/C++ for a while (another assumption of this document) will likely have run
into alloca at some point.

In this case, these assumptions are unfortunately implicit. We are trying to
move towards explicitly calling out the major assumptions about the reader's
knowledge (see guideline 2 in
http://llvm.org/docs/SphinxQuickstartTemplate.html#guidelines )

I understand that in your particular case you were reading this document
without this piece of assumed knowledge. Another reader might not know (or be
able to look up) what "x86", "GPR", "register allocation", "DAG", "VLIW", etc.
are. The line has to be drawn somewhere for what we assume and what we explain.

Furthermore, in this case, a web search for "alloca" (and "llvm alloca") brings
up plenty of results. Also "dynamic" has its common meaning in programming of
"having some aspect that cannot be known until runtime".

It is unfortunate that you came into this document without the necessary
background, but the change you are requesting is unlikely to help "the next
reader" (it won't even help you since you already know what alloca is thanks to
the discussion here). We all periodically run into these sort of things that we
"ought to know" but don't, and that require a bit of investigation to get up to
speed about. It's not a big deal and life moves on.

In fact, a change to the document that hints that the term "alloca" as used
there needs some special explanation would seem out of place and likely confuse
most other readers.

Really the only change I can think of that would be appropriate would be a
slightly more explicit wording of "runtime-sized alloca" instead of "dynamic
alloca". If that interests you please send a patch to llvm-commits and feel
free to CC me.

-- 
You are receiving this mail because:
You are on the CC list for the bug.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/llvm-bugs/attachments/20140701/307c604b/attachment.html>