Implement RFC #18

src/doc/guide-ffi.md

@@ -268,7 +268,7 @@ struct RustObject {
     // other members
 }
 
-extern fn callback(target: *mut RustObject, a:i32) {
+extern "C" fn callback(target: *mut RustObject, a:i32) {
     println!("I'm called from C with value {0}", a);
     unsafe {
         // Update the value in RustObject with the value received from the callback
@@ -505,16 +505,16 @@ to define a block for all windows systems, not just x86 ones.
 
 # Interoperability with foreign code
 
-Rust guarantees that the layout of a `struct` is compatible with the platform's representation in C.
-A `#[packed]` attribute is available, which will lay out the struct members without padding.
-However, there are currently no guarantees about the layout of an `enum`.
+Rust guarantees that the layout of a `struct` is compatible with the platform's representation in C
+only if the `#[repr(C)]` attribute is applied to it.  `#[repr(C, packed)]` can be used to lay out
+struct members without padding.  `#[repr(C)]` can also be applied to an enum.
 
-Rust's owned and managed boxes use non-nullable pointers as handles which point to the contained
+Rust's owned boxes (`Box<T>`) use non-nullable pointers as handles which point to the contained
 object. However, they should not be manually created because they are managed by internal
-allocators. References can safely be assumed to be non-nullable pointers directly to the
-type. However, breaking the borrow checking or mutability rules is not guaranteed to be safe, so
-prefer using raw pointers (`*`) if that's needed because the compiler can't make as many assumptions
-about them.
+allocators. References can safely be assumed to be non-nullable pointers directly to the type.
+However, breaking the borrow checking or mutability rules is not guaranteed to be safe, so prefer
+using raw pointers (`*`) if that's needed because the compiler can't make as many assumptions about
+them.
 
 Vectors and strings share the same basic memory layout, and utilities are available in the `vec` and
 `str` modules for working with C APIs. However, strings are not terminated with `\0`. If you need a

src/doc/rust.md

@@ -1221,6 +1221,9 @@ struct Cookie;
 let c = [Cookie, Cookie, Cookie, Cookie];
 ~~~~
 
+The precise memory layout of a structure is not specified. One can specify a
+particular layout using the [`repr` attribute](#ffi-attributes).
+
 By using the `struct_inherit` feature gate, structures may use single inheritance. A Structure may only
 inherit from a single other structure, called the _super-struct_. The inheriting structure (sub-struct)
 acts as if all fields in the super-struct were present in the sub-struct. Fields declared in a sub-struct
@@ -1851,6 +1854,23 @@ interpreted:
 - `linkage` - on a static, this specifies the [linkage
   type](http://llvm.org/docs/LangRef.html#linkage-types).
 
+On `enum`s:
+
+- `repr` - on C-like enums, this sets the underlying type used for
+  representation. Takes one argument, which is the primitive
+  type this enum should be represented for, or `C`, which specifies that it
+  should be the default `enum` size of the C ABI for that platform. Note that
+  enum representation in C is undefined, and this may be incorrect when the C
+  code is compiled with certain flags.
+
+On `struct`s:
+
+- `repr` - specifies the representation to use for this struct. Takes a list
+  of options. The currently accepted ones are `C` and `packed`, which may be
+  combined. `C` will use a C ABI comptible struct layout, and `packed` will
+  remove any padding between fields (note that this is very fragile and may
+  break platforms which require aligned access).
+
 ### Miscellaneous attributes
 
 - `link_section` - on statics and functions, this specifies the section of the
@@ -1860,12 +1880,6 @@ interpreted:
   symbol for this item to its identifier.
 - `packed` - on structs or enums, eliminate any padding that would be used to
   align fields.
-- `repr` - on C-like enums, this sets the underlying type used for
-  representation. Useful for FFI. Takes one argument, which is the primitive
-  type this enum should be represented for, or `C`, which specifies that it
-  should be the default `enum` size of the C ABI for that platform. Note that
-  enum representation in C is undefined, and this may be incorrect when the C
-  code is compiled with certain flags.
 - `simd` - on certain tuple structs, derive the arithmetic operators, which
   lower to the target's SIMD instructions, if any.
 - `static_assert` - on statics whose type is `bool`, terminates compilation