Small fixes and clarifications to user guide

Some letter casing, typing, formatting, and grammar errors are fixed.
Links added to docs.rs in some text referring to documentation there,
as well as to other external resources.

For inclusivity, the tutorial's sanity test is renamed to a smoke test.

Author: miikkas

book/src/SUMMARY.md

@@ -8,9 +8,9 @@
         - [Create a `wrapper.h` Header](./tutorial-2.md)
         - [Create a `build.rs` File](./tutorial-3.md)
         - [Include the Generated Bindings in `src/lib.rs`](./tutorial-4.md)
-        - [Write a Sanity Test](./tutorial-5.md)
+        - [Write a Smoke Test](./tutorial-5.md)
         - [Publish Your Crate!](./tutorial-6.md)
-    - [Bindings for non-system libraries](./non-system-libraries.md)
+    - [Bindings for Non-System Libraries](./non-system-libraries.md)
 - [Command Line Usage](./command-line-usage.md)
 - [Customizing the Generated Bindings](./customizing-generated-bindings.md)
     - [Allowlisting](./allowlisting.md)
@@ -20,11 +20,11 @@
     - [Preventing the Derivation of `Copy` and `Clone`](./nocopy.md)
     - [Preventing the Derivation of `Debug`](./nodebug.md)
     - [Preventing the Derivation of `Default`](./nodefault.md)
-    - [Annotating types with `#[must-use]`](./must-use-types.md)
-    - [Field visibility](./visibility.md)
-    - [Code formatting](./code-formatting.md)
+    - [Annotating Types with `#[must-use]`](./must-use-types.md)
+    - [Field Visibility](./visibility.md)
+    - [Code Formatting](./code-formatting.md)
 - [Generating Bindings to C++](./cpp.md)
-- [Generating Bindings to Objective-c](./objc.md)
+- [Generating Bindings to Objective-C](./objc.md)
 - [Using Unions](./using-unions.md)
 - [Using Bitfields](./using-bitfields.md)
 - [Using Flexible Array Members](./using-fam.md)

book/src/command-line-usage.md

@@ -13,7 +13,7 @@ directory to your `$PATH` to use `bindgen`.
 output file path for the generated bindings. If the output file path is not
 supplied, the bindings are printed to `stdout`.
 
-If we wanted to generated Rust FFI bindings from a C header named `input.h` and
+If we wanted to generate Rust FFI bindings from a C header named `input.h` and
 put them in the `bindings.rs` file, we would invoke `bindgen` like this:
 
 ```bash

book/src/faq.md

@@ -47,18 +47,18 @@ creates linking errors.
 However, if you are compiling the C/C++ yourself (rather than using a system
 shared library, for example), then you can pass `-fkeep-inline-functions` or
 `-fno-inline-functions` to `gcc` or `clang`, and invoke `bindgen` with either
-the `bindgen::Builder::generate_inline_functions` method or the
-`--generate-inline-functions` flag.
+the [`bindgen::Builder::generate_inline_functions`](https://docs.rs/bindgen/latest/bindgen/struct.Builder.html#method.generate_inline_functions)
+method or the `--generate-inline-functions` flag.
 
 Note that these functions and methods are usually marked inline for a reason:
 they tend to be hot. The above workaround makes them an out-of-line call, which
 might not provide acceptable performance.
 
 As an alternative, you can invoke `bindgen` with either the
-`bindgen::Builder::wrap_static_fns` method or the `--wrap-static-fns` flag.
-Which generates a C source file that can be compiled against the input headers
-to produce Rust headers for `static` and `static inline` functions. See [How to
-handle `static inline` functions](https://github.com/rust-lang/rust-bindgen/discussions/2405)
+[`bindgen::Builder::wrap_static_fns`](https://docs.rs/bindgen/latest/bindgen/struct.Builder.html#method.wrap_static_fns)
+method or the `--wrap-static-fns` flag. That generates a C source file that can
+be compiled against the input headers to produce Rust bindings for `static` and
+`static inline` functions. See [How to handle `static inline` functions](https://github.com/rust-lang/rust-bindgen/discussions/2405)
 for further information.
 
 ### Does `bindgen` support the C++ Standard Template Library (STL)?
@@ -81,8 +81,8 @@ possible that bindgen will generate padding fields named `__bindgen_padding_N`.
 As these fields might be present when compiling for one architecture but not
 for an other, you should not initialize these fields manually when initializing
 the struct. Instead, use the `Default` trait. You can either enable this when
-constructing the `Builder` using the `derive_default` method, or you can
-implement this per struct using:
+constructing the `Builder` using the [`derive_default`](https://docs.rs/bindgen/latest/bindgen/struct.Builder.html#method.derive_default)
+method, or you can implement this per struct using:
 
 ```rust,ignore
 impl Default for SRC_DATA {
@@ -107,7 +107,7 @@ be automatically initialized by `..Default::default()`.
 
 ### How to generate bindings for a custom target?
 
-To generate bindings for a custom target you only need to pass the `--target`
+To generate bindings for a custom target you only need to pass the [`--target`](https://clang.llvm.org/docs/ClangCommandLineReference.html#cmdoption-clang-target)
 argument to `libclang`. For example, if you want to generate bindings for the
 `armv7a-none-eabi` target using the command line, you need to invoke `bindgen`
 like so:

book/src/must-use-types.md

@@ -1,11 +1,13 @@
-# Annotating types with `#[must-use]`
+# Annotating Types with `#[must-use]`
 
 `bindgen` can be instructed to annotate certain types with 
 [`#[must_use]`](https://doc.rust-lang.org/reference/attributes/diagnostics.html#the-must_use-attribute).
 
-Some libraries have a common error type, returned by lots of their functions, 
-which needs to be checked after every call. In these cases it's useful to add `#[must_use]` to this type, so the Rust
-compiler emits a warning when the check is missing.
+Some libraries have a common error type, returned by many of their functions,
+which needs to be checked after every call. In these cases it's useful to add
+`#[must_use]` to this type, so the Rust compiler emits a warning when the check
+is missing.
+
 ### Library
 
 * [`bindgen::Builder::must_use_type`](https://docs.rs/bindgen/latest/bindgen/struct.Builder.html#method.must_use_type)

book/src/nocopy.md

@@ -4,14 +4,17 @@
 basis. Sometimes, it might not understand that although adding `#[derive(Copy,
 Clone)]` to a translated type definition will compile, it still shouldn't do
 that for reasons it can't know. In these cases, the `nocopy` annotation can be
-used to prevent bindgen to autoderive the `Copy` and `Clone` traits for a type.
+used to prevent bindgen from automatically deriving the `Copy` and `Clone`
+traits for a type.
 
 ### Library
 
+* [`bindgen::Builder::derive_copy`](https://docs.rs/bindgen/latest/bindgen/struct.Builder.html#method.derive_copy)
 * [`bindgen::Builder::no_copy`](https://docs.rs/bindgen/latest/bindgen/struct.Builder.html#method.no_copy)
 
 ### Command Line
 
+* `--no-derive-copy`
 * `--no-copy <regex>`
 
 ### Annotations

book/src/nodebug.md

@@ -3,14 +3,16 @@
 `bindgen` will attempt to derive the `Debug` traits on a best-effort
 basis. Sometimes, it might not understand that although adding `#[derive(Debug)]` to a translated type definition will compile, it still shouldn't do
 that for reasons it can't know. In these cases, the `nodebug` annotation can be
-used to prevent bindgen to autoderive the `Debug` traits for a type.
+used to prevent bindgen from automatically deriving the `Debug` trait for a type.
 
 ### Library
 
+* [`bindgen::Builder::derive_debug`](https://docs.rs/bindgen/latest/bindgen/struct.Builder.html#method.derive_debug)
 * [`bindgen::Builder::no_debug`](https://docs.rs/bindgen/latest/bindgen/struct.Builder.html#method.no_debug)
 
 ### Command Line
 
+* `--no-derive-debug`
 * `--no-debug <regex>`
 
 ### Annotations

book/src/nodefault.md

@@ -1,16 +1,20 @@
 # Preventing the Derivation of `Default`
 
+By default, `Default` is not derived.
+
 `bindgen` will attempt to derive/impl the `Default` traits on a best-effort basis.
-Sometimes, we need customize the implement of `Default` for certain types,
-In these cases, the `nodefault` annotation can be used to prevent bindgen 
-to autoderive the `Default` traits for a type.
+Sometimes, we need customize the implementation of `Default` for certain types.
+In these cases, the `nodefault` annotation can be used to prevent bindgen from
+automatically deriving the `Default` trait for a type.
 
 ### Library
 
+* [`bindgen::Builder::derive_default`](https://docs.rs/bindgen/latest/bindgen/struct.Builder.html#method.derive_default)
 * [`bindgen::Builder::no_default`](https://docs.rs/bindgen/latest/bindgen/struct.Builder.html#method.no_default)
 
 ### Command Line
 
+* `--with-derive-default`
 * `--no-default <regex>`
 
 ### Annotations

book/src/objc.md

@@ -1,25 +1,25 @@
 # Generating Bindings to Objective-C
 
-`bindgen` does not (yet) have full objective-c support but it can generate bindings
-for a lot of the apple frameworks without too much blocklisting.
+`bindgen` does not (yet) have full Objective-C support, but it can generate
+bindings for many of the Apple frameworks without too much blocklisting.
 
-In order to generate bindings, you will need `-x objective-c` as the clang
-args. If you'd like to use [block](https://crates.io/crates/block) you will need
+In order to generate bindings, you will need `-x objective-c` as a clang arg. If
+you'd like to use [block](https://crates.io/crates/block) you will need
 `-fblocks` as a clang arg as well.
 
 Depending on your setup, you may need `--generate-block` to generate the block
 function aliases and `--block-extern-crate` to insert a `extern crate block` at
 the beginning of the generated bindings. The same logic applies to the
 `--objc-extern-crate` parameter.
 
-The objective-c classes will be represented as a `struct Foo(id)` and a trait
-`IFoo` where `Foo` is the objective-c class and `id` is an alias for `*mut
-objc::runtime::Object` (the pointer to the objective-c instance). The trait
+The Objective-C classes will be represented as a `struct Foo(id)` and a trait
+`IFoo` where `Foo` is the Objective-C class and `id` is an alias for `*mut
+objc::runtime::Object` (the pointer to the Objective-C instance). The trait
 `IFoo` is needed to allow for the generated inheritance.
 
-Functions that use or return objective-c pointers of instance `Foo` will return
+Functions that use or return Objective-C pointers of instance `Foo` will return
 `Foo`. The reason this works is because `Foo` represented as `transparent`.
-This will be helpful for a lot of objective-c frameworks however there are some
+This will be helpful for many Objective-C frameworks. However, there are some
 cases where functions return `instancetype` which is a type alias for `id` so
 an occasional `foo.0` may be required. An example of this would in the UIKit
 framework should you want to add a `UILabel` to a
@@ -42,7 +42,7 @@ stands for interface.
 * Protocols which match to rust traits with prefixes of `P` which
 stands for Protocol.
 * Classes will generate `struct Foo(id)` where `Foo` is the class
-name and `id` is a pointer to the objective-c Object.
+name and `id` is a pointer to the Objective-C Object.
 * Blocks
 
 ## Useful Notes
@@ -52,16 +52,16 @@ name and `id` is a pointer to the objective-c Object.
 [here](https://github.com/rust-lang/rust-bindgen/issues/1211#issuecomment-569804287).
 * The generated bindings will almost certainly have some conflicts so you will
 have to blocklist a few things. There are a few cases of the parameters being
-poorly named in the objective-c headers. But if you're using anything with
+poorly named in the Objective-C headers. But if you're using anything with
 Core Foundation, you'll find that `time.h` as has a variable called timezone that
 conflicts with some of the things in `NSCalendar.h`.
-* Some small subset of the function headers in the apple frameworks go against
-apple's guidelines for parameter names and duplicate the names in the header
+* Some small subset of the function headers in the Apple frameworks go against
+Apple's guidelines for parameter names and duplicate the names in the header
 which won't compile as mentioned
 [here](https://github.com/rust-lang/rust-bindgen/issues/1705).
 * instancetype return methods does not return `Self` for you given class, it
 returns a `mut * objc::runtime::Objc` which is aliased as `id`. This is because
-objective-c's inheritance doesn't perfectly match that of rusts.
+Objective-C's inheritance doesn't perfectly match that of Rust's.
 * Depending on what you're trying `bindgen` against, you may end up including
 all of Core Foundation and any other frameworks. This will result in a very
 long compile time.

book/src/tutorial-5.md

@@ -1,11 +1,11 @@
-# Write a Sanity Test
+# Write a Smoke Test
 
-Finally, to tie everything together, let's write a sanity test that round trips
+Finally, to tie everything together, let's write a smoke test that round trips
 some text through compression and decompression, and then asserts that it came
 back out the same as it went in. This is a little wordy using the raw FFI
 bindings, but hopefully we wouldn't usually ask people to do this, we'd provide
 a nice Rust-y API on top of the raw FFI bindings for them. However, since this
-is for testing the bindings directly, our sanity test will use the bindings
+is for testing the bindings directly, our smoke test will use the bindings
 directly.
 
 The test data I'm round tripping are some Futurama quotes I got off the internet

book/src/using-bitfields.md

@@ -15,7 +15,7 @@ pre-existing definition for the bitfield unit type.
 
 ## Bitfield examples
 
-For this discussion, we will use the following C type definitions and functions.
+For this discussion, we will use the following C type definitions and functions:
 ```c
 typedef struct {
     unsigned int a: 1;
@@ -76,7 +76,9 @@ StructWithBitfields: a:1, b:1, c:0
 
 To create a new bitfield in Rust, use the bitfield allocation unit constructor.
 
-Note: This requires the Builder's derive_default to be set to true, otherwise the necessary Default functions won't be generated.
+Note: This requires the `Builder`'s [`derive_default`](https://docs.rs/bindgen/latest/bindgen/struct.Builder.html#method.derive_default)
+to be set to `true`. Otherwise the necessary `Default` functions won't be
+generated.
 
 ```rust,ignore
     let bfield = StructWithBitfields{