[llvm-commits] Fwd: [Patch] Exception Handling Documentation

[Bill Wendling]

On Jul 30, 2011, at 10:02 AM, Chris Lattner wrote:

> +  <a name="i_resume">'<tt>resume</tt>' Instruction</a>
> 
> Is "resume" the final name for this instruction?
> 
I have a slight preference for it above a more verbose name. But I can be convinced otherwise. I think that it's descriptive enough as it is, how it's documented, and how it's used. If you have a strong preference for resume_unwind, or something more descriptive, I can change it.

> +  clause := catch <ty> {, <ty>}*
> +  clause := filter <ty> {, <ty>}*
> 
> "ty" and "somety" imply an LLVM type, not a global variable.

I want 'somety' to be an LLVM type. I'll change the others.

> Also, don't you require a type on the global variable?  Something like "catch i32* @G" is what you're going for, right?
> 
Ah, yes.

> "is used to specify a basic block"
> -> "is used to specify that a basic block"
> 
> "is a landing pad." -> This is self referential.  You need to explain what a landing pad is, otherwise the only people that can understand this are people who already know what it does.
> 
> I would suggest adding a few paragraphs describing how EH in LLVM works to the "High Level Structure" section, probably right before "Pointer Aliasing Rules".  You can then link to it from resume/landingpad/invoke.  Here's a start:
> 
> When an exception is thrown by a runtime system, it walks up the stack looking for frames that may potentially handle it.  These frames are indicated by having call sites formed with '<a>invoke' instructions.  When the runtime system finds a frame that has an invoke in it, it transfers control flow into the function, at the point of a landingpad instruction....
> 
> This also gives you a place to put a (SIMPLE!) example or two, which is essential.
> 
There's all ready an HTML doc about exception handling and an overview, which describes the main concepts very well: http://llvm.org/docs/ExceptionHandling.html#overview Would a pointer to this be okay?

Thanks for the review!
-bw