Reworded to avoid fuzziness, mention ! in c_void docs.

14 files changed, 23 insertions, 13 deletions

diff --git a/src/libstd/os/raw/char.md b/src/libstd/os/raw/char.md
index 6816e519d1a..9a55767d965 100644
--- a/src/libstd/os/raw/char.md
+++ b/src/libstd/os/raw/char.md
@@ -1,6 +1,6 @@
 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'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. This type will always be either [`i8`] or [`u8`], as the type is defined as being one byte 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 the character `'\0'`. See [`CStr`] for more information.
 
diff --git a/src/libstd/os/raw/double.md b/src/libstd/os/raw/double.md
index 5ac09ee284c..6818dada317 100644
--- a/src/libstd/os/raw/double.md
+++ b/src/libstd/os/raw/double.md
@@ -1,6 +1,7 @@
 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`].
+This type will almost always be [`f64`], which is guaranteed to be an [IEEE-754 double-precision float] in Rust. That said, the standard technically only guarantees that it be a floating-point number with at least the precision of a [`float`], and it may be `f32` or something entirely different from the IEEE-754 standard.
 
+[IEEE-754 double-precision float]: https://en.wikipedia.org/wiki/IEEE_754
 [`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
index 20ba8645055..57d1071d0da 100644
--- a/src/libstd/os/raw/float.md
+++ b/src/libstd/os/raw/float.md
@@ -1,5 +1,6 @@
 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.
+This type will almost always be [`f32`], which is guaranteed to be an [IEEE-754 single-precision float] in Rust. That said, the standard technically only guarantees that it be a floating-point number, and it may have less precision than `f32` or not follow the IEEE-754 standard at all.
 
+[IEEE-754 single-precision float]: https://en.wikipedia.org/wiki/IEEE_754
 [`f32`]: ../../primitive.f32.html
diff --git a/src/libstd/os/raw/int.md b/src/libstd/os/raw/int.md
index efe7786099a..a0d25fd21d8 100644
--- a/src/libstd/os/raw/int.md
+++ b/src/libstd/os/raw/int.md
@@ -1,6 +1,7 @@
 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`].
+This type will almost always be [`i32`], but may differ on some esoteric systems. The C standard technically only requires that this type be a signed integer that is at least the size of a [`short`]; some systems define it as an [`i16`], for example.
 
 [`short`]: type.c_short.html
 [`i32`]: ../../primitive.i32.html
+[`i16`]: ../../primitive.i16.html
diff --git a/src/libstd/os/raw/long.md b/src/libstd/os/raw/long.md
index 5a2e2331c0a..c620b402819 100644
--- a/src/libstd/os/raw/long.md
+++ b/src/libstd/os/raw/long.md
@@ -1,6 +1,6 @@
 Equivalent to C's `signed long` (`long`) type.
 
-This type will usually be [`i64`], but is sometimes [`i32`]. Technically, the standard only requires that it be at least 32 bits, or at least the size of an [`int`].
+This type will always be [`i32`] or [`i64`]. Most notably, many Linux-based systems assume an `i64`, but Windows assumes `i32`. The C standard technically only requires that this type be a signed integer that is at least 32 bits and at least the size of an [`int`], although in practice, no system would have a `long` that is neither an `i32` nor `i64`.
 
 [`int`]: type.c_int.html
 [`i32`]: ../../primitive.i32.html
diff --git a/src/libstd/os/raw/longlong.md b/src/libstd/os/raw/longlong.md
index 6594fcd564c..ab3d6436568 100644
--- a/src/libstd/os/raw/longlong.md
+++ b/src/libstd/os/raw/longlong.md
@@ -1,6 +1,7 @@
 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`].
+This type will almost always be [`i64`], but may differ on some systems. The C standard technically only requires that this type be a signed integer that is at least 64 bits and at least the size of a [`long`], although in practice, no system would have a `long long` that is not an `i64`, as most systems do not have a standardised [`i128`] type.
 
 [`long`]: type.c_int.html
 [`i64`]: ../../primitive.i64.html
+[`i128`]: ../../primitive.i128.html
diff --git a/src/libstd/os/raw/mod.rs b/src/libstd/os/raw/mod.rs
index 710976ed8e0..d5eeb5252f0 100644
--- a/src/libstd/os/raw/mod.rs
+++ b/src/libstd/os/raw/mod.rs
@@ -83,6 +83,10 @@ use fmt;
 /// 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.
 ///
+/// Ideally, this type would be equivalent to [`!`], but currently it may
+/// be more ideal to use `c_void` for FFI purposes.
+///
+/// [`!`]: ../../primitive.never.html
 /// [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
diff --git a/src/libstd/os/raw/schar.md b/src/libstd/os/raw/schar.md
index 42a403ef5d7..6aa8b1211d8 100644
--- a/src/libstd/os/raw/schar.md
+++ b/src/libstd/os/raw/schar.md
@@ -1,6 +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.
+This type will always be [`i8`], but is included for completeness. It is defined as being a signed integer the same size as a C [`char`].
 
 [`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
index 86a8495eae2..be92c6c106d 100644
--- a/src/libstd/os/raw/short.md
+++ b/src/libstd/os/raw/short.md
@@ -1,6 +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`].
+This type will almost always be [`i16`], but may differ on some esoteric systems. The C standard technically only requires that this type be a signed integer with at least 16 bits; some systems may define it as `i32`, for example.
 
 [`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
index a5b74170229..b6ca711f869 100644
--- a/src/libstd/os/raw/uchar.md
+++ b/src/libstd/os/raw/uchar.md
@@ -1,6 +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.
+This type will always be [`u8`], but is included for completeness. It is defined as being an unsigned integer the same size as a C [`char`].
 
 [`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
index ec4714a9ab4..1e710f804c4 100644
--- a/src/libstd/os/raw/uint.md
+++ b/src/libstd/os/raw/uint.md
@@ -1,6 +1,7 @@
 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.
+This type will almost always be [`u16`], but may differ on some esoteric systems. The C standard technically only requires that this type be an unsigned integer with the same size as an [`int`]; some systems define it as a [`u16`], for example.
 
 [`int`]: type.c_int.html
 [`u32`]: ../../primitive.u32.html
+[`u16`]: ../../primitive.u16.html
diff --git a/src/libstd/os/raw/ulong.md b/src/libstd/os/raw/ulong.md
index 919de171a39..c350395080e 100644
--- a/src/libstd/os/raw/ulong.md
+++ b/src/libstd/os/raw/ulong.md
@@ -1,6 +1,6 @@
 Equivalent to C's `unsigned long` type.
 
-This type will usually be [`u64`], but is sometimes [`u32`]. Technically, the standard only requires that it be the same size as a [`long`], which isn't very clear-cut.
+This type will always be [`u32`] or [`u64`]. Most notably, many Linux-based systems assume an `u64`, but Windows assumes `u32`. The C standard technically only requires that this type be an unsigned integer with the size of a [`long`], although in practice, no system would have a `ulong` that is neither a `u32` nor `u64`.
 
 [`long`]: type.c_long.html
 [`u32`]: ../../primitive.u32.html
diff --git a/src/libstd/os/raw/ulonglong.md b/src/libstd/os/raw/ulonglong.md
index 9f5ff74f261..c41faf74c5c 100644
--- a/src/libstd/os/raw/ulonglong.md
+++ b/src/libstd/os/raw/ulonglong.md
@@ -1,6 +1,7 @@
 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.
+This type will almost always be [`u64`], but may differ on some systems. The C standard technically only requires that this type be an unsigned integer with the size of a [`long long`], although in practice, no system would have a `long long` that is not a `u64`, as most systems do not have a standardised [`u128`] type.
 
 [`long long`]: type.c_longlong.html
 [`u64`]: ../../primitive.u64.html
+[`u128`]: ../../primitive.u128.html
diff --git a/src/libstd/os/raw/ushort.md b/src/libstd/os/raw/ushort.md
index 6dea582fda2..d364abb3c8e 100644
--- a/src/libstd/os/raw/ushort.md
+++ b/src/libstd/os/raw/ushort.md
@@ -1,6 +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.
+This type will almost always be [`u16`], but may differ on some esoteric systems. The C standard technically only requires that this type be an unsigned integer with the same size as a [`short`].
 
 [`short`]: type.c_short.html
 [`u16`]: ../../primitive.u16.html