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.
diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md
index daaed04..ac57aaa 100644
--- a/book/src/SUMMARY.md
+++ b/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)
diff --git a/book/src/command-line-usage.md b/book/src/command-line-usage.md
index b3356d7..051a63e 100644
--- a/book/src/command-line-usage.md
+++ b/book/src/command-line-usage.md
@@ -13,7 +13,7 @@
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
diff --git a/book/src/faq.md b/book/src/faq.md
index bbaaab6..59699ac 100644
--- a/book/src/faq.md
+++ b/book/src/faq.md
@@ -47,18 +47,18 @@
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 @@
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 @@
### 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:
diff --git a/book/src/must-use-types.md b/book/src/must-use-types.md
index 490339c..1792e5a 100644
--- a/book/src/must-use-types.md
+++ b/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)
diff --git a/book/src/nocopy.md b/book/src/nocopy.md
index 8a637a5..e0d17ed 100644
--- a/book/src/nocopy.md
+++ b/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
diff --git a/book/src/nodebug.md b/book/src/nodebug.md
index c412a7d..4fa8201 100644
--- a/book/src/nodebug.md
+++ b/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
diff --git a/book/src/nodefault.md b/book/src/nodefault.md
index 37896f6..9561d7c 100644
--- a/book/src/nodefault.md
+++ b/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
diff --git a/book/src/objc.md b/book/src/objc.md
index ed6f2cb..3845ed5 100644
--- a/book/src/objc.md
+++ b/book/src/objc.md
@@ -1,10 +1,10 @@
# 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
@@ -12,14 +12,14 @@
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 @@
* 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 @@
[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.
diff --git a/book/src/tutorial-5.md b/book/src/tutorial-5.md
index 8a71dac..8e308f8 100644
--- a/book/src/tutorial-5.md
+++ b/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
diff --git a/book/src/using-bitfields.md b/book/src/using-bitfields.md
index 8929f73..6aaab22 100644
--- a/book/src/using-bitfields.md
+++ b/book/src/using-bitfields.md
@@ -15,7 +15,7 @@
## 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 @@
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{
