Small fixes and clarifications to user guide

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{