Improve comments and docs relating to char16_t.

Part of google/autocxx#124

Author: adetaylor

bindgen/codegen/helpers.rs

@@ -191,7 +191,7 @@ pub(crate) mod ast_ty {
             // argument is used. bindgen_cchar16_t is not a real type;
             // but this allows downstream postprocessors to distinguish
             // this case and do something special for C++ bindings
-            // containing char16_t.
+            // containing the C++ type char16_t.
             IntKind::Char16 => syn::parse_quote! { bindgen_cchar16_t },
             IntKind::SChar => raw_type(ctx, "c_schar"),
             IntKind::UChar => raw_type(ctx, "c_uchar"),

bindgen/ir/int.rs

@@ -57,7 +57,7 @@ pub enum IntKind {
     /// A 16-bit integer, used only for enum size representation.
     U16,
 
-    /// Either a `char16_t` or a `wchar_t`.
+    /// The C++ type `char16_t`, which is its own type (unlike in C).
     Char16,
 
     /// A 32-bit signed integer.

bindgen/options/mod.rs

@@ -153,10 +153,13 @@ macro_rules! options {
 }
 
 options! {
-    /// Whether we should distinguish between 'char16_t' and 'u16'.
-    /// As standard, bindgen represents `char16_t` as `u16`.
+    /// Whether we should distinguish between C++'s 'char16_t' and 'u16'.
+    /// The C++ type `char16_t` is its own special type; it's not a typedef
+    /// of some other integer (this differs from C).
+    /// As standard, bindgen represents C++ `char16_t` as `u16`.
     /// Rust does not have a `std::os::raw::c_char16_t` type, and thus
-    /// we can't use a built-in Rust type in the generated bindings.
+    /// we can't use a built-in Rust type in the generated bindings (and
+    /// nor would it be appropriate as it's a C++-specific type.)
     /// But for some uses of bindgen, especially when downstream
     /// post-processing occurs, it's important to distinguish `char16_t`
     /// from normal `uint16_t`. When this option is enabled, bindgen