[LLVMdev] Reference Manual Clarifications 2

[Jon Sargeant]

Chris Lattner wrote:
> On Mon, 31 Mar 2008, Jon Sargeant wrote:
>> I'm attaching another round of changes.  Please verify that they are correct.
> 
> Applied with edits:
> http://lists.cs.uiuc.edu/pipermail/llvm-commits/Week-of-Mon-20080331/060556.html
> 
> I figured out what your patches don't apply.  Something (your web browser, 
> editor, etc) is stripping trailing whitespace.
> 
> -Chris
> 

Hmm, I realized that the alignment doesn't have a type in front of it 
(unlike NumElements) so it's reasonably clear that it's a constant. 
Saying "constant alignment" isn't necessary.

Regarding malloc, I think your wording isn't clear enough: "Allocating 
zero bytes is undefined."  My understanding is that an undefined 
operation is illegal; however, the implementation is not required to 
diagnose it.  Allocating zero bytes is legal; it's just that the result 
is meaningless.  Consider rewording as "Allocating zero bytes is legal, 
but the result is undefined.  The result of a zero-sized allocation is a 
valid argument for free."

Regarding free, I also think your wording isn't clear enough: "If the 
pointer is null, the result is undefined."  The free result is void.
Consider rewording as "If the pointer is null, the operation is valid 
but does not free the pointer."

Regarding alloca, please add "The operation is undefined if there is 
insufficient memory available."

Regarding malloc and alloca, I realized that the size is unsigned, so a 
negative value for NumElements is impossible.  I suggest replacing "it 
is the number of elements allocated" with "it is the UNSIGNED number of 
elements allocated".

Regarding shl, ashr, and lshr, please add "The second argument is 
interpreted as an unsigned value."

Regarding unwind, replace "The 'unwind' intrinsic" with "The 'unwind' 
instruction"

I'm working on another set of changes now.  If it's not too much 
trouble, it would be more convenient for me to post the changes (as I've 
done in this e-mail) and let you integrate them into LangRef.html.

Best Regards,
Jon