Document std::os::raw.

15 files changed, 116 insertions, 5 deletions

diff --git a/src/libstd/lib.rs b/src/libstd/lib.rs
index a8049e676b3..642fa8775a4 100644
--- a/src/libstd/lib.rs
+++ b/src/libstd/lib.rs
@@ -260,6 +260,7 @@
 #![feature(core_intrinsics)]
 #![feature(dropck_eyepatch)]
 #![feature(exact_size_is_empty)]
+#![feature(external_doc)]
 #![feature(fs_read_write)]
 #![feature(fixed_size_array)]
 #![feature(float_from_str_radix)]
diff --git a/src/libstd/os/raw/char.md b/src/libstd/os/raw/char.md
new file mode 100644
index 00000000000..fb47dff187e
--- /dev/null
+++ b/src/libstd/os/raw/char.md
@@ -0,0 +1,11 @@
+Equivalent to C's `char` type.
+
+[C's `char` type] is completely unlike [Rust's `char` type]; while Rust's type represents a unicode scalar value, C's `char` type is just an ordinary integer. In practice, this type will always be either [`i8`] or [`u8`], but you're technically not supposed to rely on this behaviour, as the standard only defines a char as being at least eight bits long.
+
+C chars are most commonly used to make C strings. Unlike Rust, where the length of a string is included alongside the string, C strings mark the end of a string with a zero. See [`CStr`] for more information.
+
+[C's `char` type]: https://en.wikipedia.org/wiki/C_data_types#Basic_types
+[Rust's `char` type]: ../../primitive.char.html
+[`CStr`]: ../../ffi/struct.CStr.html
+[`i8`]: ../../primitive.i8.html
+[`u8`]: ../../primitive.u8.html
diff --git a/src/libstd/os/raw/double.md b/src/libstd/os/raw/double.md
new file mode 100644
index 00000000000..5ac09ee284c
--- /dev/null
+++ b/src/libstd/os/raw/double.md
@@ -0,0 +1,6 @@
+Equivalent to C's `double` type.
+
+This type will almost always be [`f64`], however, the standard technically only guarantees that it be a floating-point number with at least the precision of a [`float`].
+
+[`float`]: type.c_float.html
+[`f64`]: ../../primitive.f64.html
diff --git a/src/libstd/os/raw/float.md b/src/libstd/os/raw/float.md
new file mode 100644
index 00000000000..20ba8645055
--- /dev/null
+++ b/src/libstd/os/raw/float.md
@@ -0,0 +1,5 @@
+Equivalent to C's `float` type.
+
+This type will almost always be [`f32`], however, the standard technically only guarantees that it be a floating-point number.
+
+[`f32`]: ../../primitive.f32.html
diff --git a/src/libstd/os/raw/int.md b/src/libstd/os/raw/int.md
new file mode 100644
index 00000000000..efe7786099a
--- /dev/null
+++ b/src/libstd/os/raw/int.md
@@ -0,0 +1,6 @@
+Equivalent to C's `signed int` (`int`) type.
+
+This type will almost always be [`i32`], however, the standard technically only requires that it be at least the size of a [`short`].
+
+[`short`]: type.c_short.html
+[`i32`]: ../../primitive.i32.html
diff --git a/src/libstd/os/raw/long.md b/src/libstd/os/raw/long.md
new file mode 100644
index 00000000000..c281e017336
--- /dev/null
+++ b/src/libstd/os/raw/long.md
@@ -0,0 +1,8 @@
+Equivalent to C's `signed long` (`long`) type.
+
+This type will usually be [`i64`], but is sometimes [`i32`] \(i.e. [`isize`]\) on 32-bit systems. Technically, the standard only requires that it be at least 32 bits, or at least the size of an [`int`].
+
+[`int`]: type.c_int.html
+[`i32`]: ../../primitive.i32.html
+[`i64`]: ../../primitive.i64.html
+[`isize`]: ../../primitive.isize.html
diff --git a/src/libstd/os/raw/longlong.md b/src/libstd/os/raw/longlong.md
new file mode 100644
index 00000000000..6594fcd564c
--- /dev/null
+++ b/src/libstd/os/raw/longlong.md
@@ -0,0 +1,6 @@
+Equivalent to C's `signed long long` (`long long`) type.
+
+This type will almost always be [`i64`], however, the standard technically only requires that it be at least 64 bits, or at least the size of an [`long`].
+
+[`long`]: type.c_int.html
+[`i64`]: ../../primitive.i64.html
diff --git a/src/libstd/os/raw.rs b/src/libstd/os/raw/mod.rs
index 279caf8053a..e96ba045ce7 100644
--- a/src/libstd/os/raw.rs
+++ b/src/libstd/os/raw/mod.rs
@@ -8,12 +8,19 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-//! Raw OS-specific types for the current platform/architecture
+//! Platform-specific types, as defined by C.
+//!
+//! Code that interacts via FFI will almost certainly be using the
+//! base types provided by C, which aren't nearly as nicely defined
+//! as Rust's primitive types. This module provides types which will
+//! match those defined by C, so that code that interacts with C will
+//! refer to the correct types.
 
 #![stable(feature = "raw_os", since = "1.1.0")]
 
 use fmt;
 
+#[doc(include = "os/raw/char.md")]
 #[cfg(any(all(target_os = "linux", any(target_arch = "aarch64",
                                        target_arch = "arm",
                                        target_arch = "powerpc",
@@ -25,6 +32,7 @@ use fmt;
           all(target_os = "openbsd", target_arch = "aarch64"),
           all(target_os = "fuchsia", target_arch = "aarch64")))]
 #[stable(feature = "raw_os", since = "1.1.0")] pub type c_char = u8;
+#[doc(include = "os/raw/char.md")]
 #[cfg(not(any(all(target_os = "linux", any(target_arch = "aarch64",
                                            target_arch = "arm",
                                            target_arch = "powerpc",
@@ -36,30 +44,46 @@ use fmt;
               all(target_os = "openbsd", target_arch = "aarch64"),
               all(target_os = "fuchsia", target_arch = "aarch64"))))]
 #[stable(feature = "raw_os", since = "1.1.0")] pub type c_char = i8;
+#[doc(include = "os/raw/schar.md")]
 #[stable(feature = "raw_os", since = "1.1.0")] pub type c_schar = i8;
+#[doc(include = "os/raw/uchar.md")]
 #[stable(feature = "raw_os", since = "1.1.0")] pub type c_uchar = u8;
+#[doc(include = "os/raw/short.md")]
 #[stable(feature = "raw_os", since = "1.1.0")] pub type c_short = i16;
+#[doc(include = "os/raw/ushort.md")]
 #[stable(feature = "raw_os", since = "1.1.0")] pub type c_ushort = u16;
+#[doc(include = "os/raw/int.md")]
 #[stable(feature = "raw_os", since = "1.1.0")] pub type c_int = i32;
+#[doc(include = "os/raw/uint.md")]
 #[stable(feature = "raw_os", since = "1.1.0")] pub type c_uint = u32;
+#[doc(include = "os/raw/long.md")]
 #[cfg(any(target_pointer_width = "32", windows))]
 #[stable(feature = "raw_os", since = "1.1.0")] pub type c_long = i32;
+#[doc(include = "os/raw/ulong.md")]
 #[cfg(any(target_pointer_width = "32", windows))]
 #[stable(feature = "raw_os", since = "1.1.0")] pub type c_ulong = u32;
+#[doc(include = "os/raw/long.md")]
 #[cfg(all(target_pointer_width = "64", not(windows)))]
 #[stable(feature = "raw_os", since = "1.1.0")] pub type c_long = i64;
+#[doc(include = "os/raw/ulong.md")]
 #[cfg(all(target_pointer_width = "64", not(windows)))]
 #[stable(feature = "raw_os", since = "1.1.0")] pub type c_ulong = u64;
+#[doc(include = "os/raw/longlong.md")]
 #[stable(feature = "raw_os", since = "1.1.0")] pub type c_longlong = i64;
+#[doc(include = "os/raw/ulonglong.md")]
 #[stable(feature = "raw_os", since = "1.1.0")] pub type c_ulonglong = u64;
+#[doc(include = "os/raw/float.md")]
 #[stable(feature = "raw_os", since = "1.1.0")] pub type c_float = f32;
+#[doc(include = "os/raw/double.md")]
 #[stable(feature = "raw_os", since = "1.1.0")] pub type c_double = f64;
 
-/// Type used to construct void pointers for use with C.
+/// Equivalent to C's `void` type when used as a [pointer].
 ///
-/// This type is only useful as a pointer target. Do not use it as a
-/// return type for FFI functions which have the `void` return type in
-/// C. Use the unit type `()` or omit the return type instead.
+/// In essence, `*const c_void` is equivalent to C's `const void*`
+/// and `*mut c_void` is equivalent to C's `void*`. That said, this is
+/// *not* the same as C's `void` return type, which is Rust's `()` type.
+///
+/// [pointer]: ../primitive.pointer.html
 // NB: For LLVM to recognize the void pointer type and by extension
 //     functions like malloc(), we need to have it represented as i8* in
 //     LLVM bitcode. The enum used here ensures this and prevents misuse
diff --git a/src/libstd/os/raw/schar.md b/src/libstd/os/raw/schar.md
new file mode 100644
index 00000000000..42a403ef5d7
--- /dev/null
+++ b/src/libstd/os/raw/schar.md
@@ -0,0 +1,6 @@
+Equivalent to C's `signed char` type.
+
+This type will almost always be [`i8`], but its size is technically equal to the size of a C [`char`], which isn't very clear-cut.
+
+[`char`]: type.c_char.html
+[`i8`]: ../../primitive.i8.html
diff --git a/src/libstd/os/raw/short.md b/src/libstd/os/raw/short.md
new file mode 100644
index 00000000000..86a8495eae2
--- /dev/null
+++ b/src/libstd/os/raw/short.md
@@ -0,0 +1,6 @@
+Equivalent to C's `signed short` (`short`) type.
+
+This type will almost always be [`i16`], however, the standard technically only requires that it be at least 16 bits, or at least the size of a C [`char`].
+
+[`char`]: type.c_char.html
+[`i16`]: ../../primitive.i16.html
diff --git a/src/libstd/os/raw/uchar.md b/src/libstd/os/raw/uchar.md
new file mode 100644
index 00000000000..a5b74170229
--- /dev/null
+++ b/src/libstd/os/raw/uchar.md
@@ -0,0 +1,6 @@
+Equivalent to C's `unsigned char` type.
+
+This type will almost always be [`u8`], but its size is technically equal to the size of a C [`char`], which isn't very clear-cut.
+
+[`char`]: type.c_char.html
+[`u8`]: ../../primitive.u8.html
diff --git a/src/libstd/os/raw/uint.md b/src/libstd/os/raw/uint.md
new file mode 100644
index 00000000000..ec4714a9ab4
--- /dev/null
+++ b/src/libstd/os/raw/uint.md
@@ -0,0 +1,6 @@
+Equivalent to C's `unsigned int` type.
+
+This type will almost always be [`u32`], however, the standard technically on requires that it be the same size as an [`int`], which isn't very clear-cut.
+
+[`int`]: type.c_int.html
+[`u32`]: ../../primitive.u32.html
diff --git a/src/libstd/os/raw/ulong.md b/src/libstd/os/raw/ulong.md
new file mode 100644
index 00000000000..3cdbc6f59bf
--- /dev/null
+++ b/src/libstd/os/raw/ulong.md
@@ -0,0 +1,8 @@
+Equivalent to C's `unsigned long` type.
+
+This type will usually be [`u64`], but is sometimes [`u32`] \(i.e. [`usize`]\) on 32-bit systems. Technically, the standard only requires that it be the same size as a [`long`], which isn't very clear-cut.
+
+[`long`]: type.c_long.html
+[`u32`]: ../../primitive.u32.html
+[`u64`]: ../../primitive.u64.html
+[`usize`]: ../../primitive.usize.html
diff --git a/src/libstd/os/raw/ulonglong.md b/src/libstd/os/raw/ulonglong.md
new file mode 100644
index 00000000000..9f5ff74f261
--- /dev/null
+++ b/src/libstd/os/raw/ulonglong.md
@@ -0,0 +1,6 @@
+Equivalent to C's `unsigned long long` type.
+
+This type will almost always be [`u64`], however, the standard technically only requires that it be the same size as a [`long long`], which isn't very clear-cut.
+
+[`long long`]: type.c_longlong.html
+[`u64`]: ../../primitive.u64.html
diff --git a/src/libstd/os/raw/ushort.md b/src/libstd/os/raw/ushort.md
new file mode 100644
index 00000000000..6dea582fda2
--- /dev/null
+++ b/src/libstd/os/raw/ushort.md
@@ -0,0 +1,6 @@
+Equivalent to C's `unsigned short` type.
+
+This type will almost always be [`u16`], however, the standard technically only requires that it be the same size as a [`short`], which isn't very clear-cut.
+
+[`short`]: type.c_short.html
+[`u16`]: ../../primitive.u16.html