Add docs workflow (#2493)

* Add `docs` workflow * Fix documentation warnings
rust-lang · Apr 10, 2023 · fa8dd50 · fa8dd50
1 parent 2bcff0f
commit fa8dd50
Show file tree

Hide file tree

Showing 10 changed files with 84 additions and 68 deletions.
diff --git a/.github/workflows/bindgen.yml b/.github/workflows/bindgen.yml
@@ -71,6 +71,23 @@ jobs:
       - name: Check without default features 
         run: cargo check -p bindgen --no-default-features --features=runtime 
 
+  docs:
+    runs-on: ubuntu-latest
+    env:
+      RUSTDOCFLAGS: -D warnings
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Install stable
+        uses: actions-rs/toolchain@v1
+        with:
+          profile: minimal
+          toolchain: stable
+          override: true
+
+      - name: Generate documentation 
+        run: cargo doc --document-private-items 
+
   quickchecking:
     runs-on: ubuntu-latest
     steps:

diff --git a/bindgen-cli/options.rs b/bindgen-cli/options.rs
@@ -54,22 +54,22 @@ struct BindgenCommand {
     /// The default style of code used to generate enums.
     #[arg(long, value_name = "VARIANT")]
     default_enum_style: Option<EnumVariation>,
-    /// Mark any enum whose name matches <REGEX> as a set of bitfield flags.
+    /// Mark any enum whose name matches REGEX as a set of bitfield flags.
     #[arg(long, value_name = "REGEX")]
     bitfield_enum: Vec<String>,
-    /// Mark any enum whose name matches <REGEX> as a newtype.
+    /// Mark any enum whose name matches REGEX as a newtype.
     #[arg(long, value_name = "REGEX")]
     newtype_enum: Vec<String>,
-    /// Mark any enum whose name matches <REGEX> as a global newtype.
+    /// Mark any enum whose name matches REGEX as a global newtype.
     #[arg(long, value_name = "REGEX")]
     newtype_global_enum: Vec<String>,
-    /// Mark any enum whose name matches <REGEX> as a Rust enum.
+    /// Mark any enum whose name matches REGEX as a Rust enum.
     #[arg(long, value_name = "REGEX")]
     rustified_enum: Vec<String>,
-    /// Mark any enum whose name matches <REGEX> as a series of constants.
+    /// Mark any enum whose name matches REGEX as a series of constants.
     #[arg(long, value_name = "REGEX")]
     constified_enum: Vec<String>,
-    /// Mark any enum whose name matches <regex> as a module of constants.
+    /// Mark any enum whose name matches REGEX as a module of constants.
     #[arg(long, value_name = "REGEX")]
     constified_enum_module: Vec<String>,
     /// The default signed/unsigned type for C macro constants.
@@ -78,34 +78,34 @@ struct BindgenCommand {
     /// The default style of code used to generate typedefs.
     #[arg(long, value_name = "VARIANT")]
     default_alias_style: Option<AliasVariation>,
-    /// Mark any typedef alias whose name matches <REGEX> to use normal type aliasing.
+    /// Mark any typedef alias whose name matches REGEX to use normal type aliasing.
     #[arg(long, value_name = "REGEX")]
     normal_alias: Vec<String>,
-    /// Mark any typedef alias whose name matches <REGEX> to have a new type generated for it.
+    /// Mark any typedef alias whose name matches REGEX to have a new type generated for it.
     #[arg(long, value_name = "REGEX")]
     new_type_alias: Vec<String>,
-    /// Mark any typedef alias whose name matches <REGEX> to have a new type with Deref and DerefMut to the inner type.
+    /// Mark any typedef alias whose name matches REGEX to have a new type with Deref and DerefMut to the inner type.
     #[arg(long, value_name = "REGEX")]
     new_type_alias_deref: Vec<String>,
     /// The default style of code used to generate unions with non-Copy members. Note that ManuallyDrop was first stabilized in Rust 1.20.0.
     #[arg(long, value_name = "STYLE")]
     default_non_copy_union_style: Option<NonCopyUnionStyle>,
-    /// Mark any union whose name matches <REGEX> and who has a non-Copy member to use a bindgen-generated wrapper for fields.
+    /// Mark any union whose name matches REGEX and who has a non-Copy member to use a bindgen-generated wrapper for fields.
     #[arg(long, value_name = "REGEX")]
     bindgen_wrapper_union: Vec<String>,
-    /// Mark any union whose name matches <REGEX> and who has a non-Copy member to use ManuallyDrop (stabilized in Rust 1.20.0) for fields.
+    /// Mark any union whose name matches REGEX and who has a non-Copy member to use ManuallyDrop (stabilized in Rust 1.20.0) for fields.
     #[arg(long, value_name = "REGEX")]
     manually_drop_union: Vec<String>,
-    /// Mark <TYPE> as hidden.
+    /// Mark TYPE as hidden.
     #[arg(long, value_name = "TYPE")]
     blocklist_type: Vec<String>,
-    /// Mark <FUNCTION> as hidden.
+    /// Mark FUNCTION as hidden.
     #[arg(long, value_name = "FUNCTION")]
     blocklist_function: Vec<String>,
-    /// Mark <ITEM> as hidden.
+    /// Mark ITEM as hidden.
     #[arg(long, value_name = "ITEM")]
     blocklist_item: Vec<String>,
-    /// Mark <FILE> as hidden.
+    /// Mark FILE as hidden.
     #[arg(long, value_name = "FILE")]
     blocklist_file: Vec<String>,
     /// Avoid generating layout tests for any type.
@@ -144,7 +144,7 @@ struct BindgenCommand {
     /// Derive Ord on any type.
     #[arg(long)]
     with_derive_ord: bool,
-    /// Avoid including doc comments in the output, see: https://github.com/rust-lang/rust-bindgen/issues/426
+    /// Avoid including doc comments in the output, see: <https://github.com/rust-lang/rust-bindgen/issues/426>
     #[arg(long)]
     no_doc_comments: bool,
     /// Disable allowlisting types recursively. This will cause bindgen to emit Rust code that won't compile! See the `bindgen::Builder::allowlist_recursively` method's documentation for details.
@@ -219,10 +219,10 @@ struct BindgenCommand {
     /// Try to fit macro constants into types smaller than u32/i32
     #[arg(long)]
     fit_macro_constant_types: bool,
-    /// Mark <TYPE> as opaque.
+    /// Mark TYPE as opaque.
     #[arg(long, value_name = "TYPE")]
     opaque_type: Vec<String>,
-    ///  Write Rust bindings to <OUTPUT>.
+    ///  Write Rust bindings to OUTPUT.
     #[arg(long, short, value_name = "OUTPUT")]
     output: Option<String>,
     /// Add a raw line of Rust code at the beginning of output.
@@ -239,19 +239,19 @@ struct BindgenCommand {
     /// Conservatively generate inline namespaces to avoid name conflicts.
     #[arg(long)]
     conservative_inline_namespaces: bool,
-    /// Allowlist all the free-standing functions matching <REGEX>. Other non-allowlisted functions will not be generated.
+    /// Allowlist all the free-standing functions matching REGEX. Other non-allowlisted functions will not be generated.
     #[arg(long, value_name = "REGEX")]
     allowlist_function: Vec<String>,
     /// Generate inline functions.
     #[arg(long)]
     generate_inline_functions: bool,
-    /// Only generate types matching <REGEX>. Other non-allowlisted types will not be generated.
+    /// Only generate types matching REGEX. Other non-allowlisted types will not be generated.
     #[arg(long, value_name = "REGEX")]
     allowlist_type: Vec<String>,
-    /// Allowlist all the free-standing variables matching <REGEX>. Other non-allowlisted variables will not be generated.
+    /// Allowlist all the free-standing variables matching REGEX. Other non-allowlisted variables will not be generated.
     #[arg(long, value_name = "REGEX")]
     allowlist_var: Vec<String>,
-    /// Allowlist all contents of <PATH>.
+    /// Allowlist all contents of PATH.
     #[arg(long, value_name = "PATH")]
     allowlist_file: Vec<String>,
     /// Print verbose error messages.
@@ -280,25 +280,25 @@ struct BindgenCommand {
     /// The absolute path to the rustfmt configuration file. The configuration file will be used for formatting the bindings. This parameter sets `formatter` to `rustfmt`.
     #[arg(long, value_name = "PATH", conflicts_with = "no_rustfmt_bindings")]
     rustfmt_configuration_file: Option<String>,
-    /// Avoid deriving PartialEq for types matching <REGEX>.
+    /// Avoid deriving PartialEq for types matching REGEX.
     #[arg(long, value_name = "REGEX")]
     no_partialeq: Vec<String>,
-    /// Avoid deriving Copy and Clone for types matching <REGEX>.
+    /// Avoid deriving Copy and Clone for types matching REGEX.
     #[arg(long, value_name = "REGEX")]
     no_copy: Vec<String>,
-    /// Avoid deriving Debug for types matching <REGEX>.
+    /// Avoid deriving Debug for types matching REGEX.
     #[arg(long, value_name = "REGEX")]
     no_debug: Vec<String>,
-    /// Avoid deriving/implementing Default for types matching <REGEX>.
+    /// Avoid deriving/implementing Default for types matching REGEX.
     #[arg(long, value_name = "REGEX")]
     no_default: Vec<String>,
-    /// Avoid deriving Hash for types matching <REGEX>.
+    /// Avoid deriving Hash for types matching REGEX.
     #[arg(long, value_name = "REGEX")]
     no_hash: Vec<String>,
-    /// Add #[must_use] annotation to types matching <REGEX>.
+    /// Add `#[must_use]` annotation to types matching REGEX.
     #[arg(long, value_name = "REGEX")]
     must_use_type: Vec<String>,
-    /// Enables detecting unexposed attributes in functions (slow). Used to generate #[must_use] annotations.
+    /// Enables detecting unexposed attributes in functions (slow). Used to generate `#[must_use]` annotations.
     #[arg(long)]
     enable_function_attribute_detection: bool,
     /// Use `*const [T; size]` instead of `*const T` for C arrays
@@ -337,22 +337,22 @@ struct BindgenCommand {
     /// Deduplicates extern blocks.
     #[arg(long)]
     merge_extern_blocks: bool,
-    /// Overrides the ABI of functions matching <regex>. The <OVERRIDE> value must be of the shape <REGEX>=<ABI> where <ABI> can be one of C, stdcall, efiapi, fastcall, thiscall, aapcs, win64 or C-unwind.
+    /// Overrides the ABI of functions matching REGEX. The OVERRIDE value must be of the shape REGEX=ABI where ABI can be one of C, stdcall, efiapi, fastcall, thiscall, aapcs, win64 or C-unwind.
     #[arg(long, value_name = "OVERRIDE")]
     override_abi: Vec<String>,
     /// Wrap unsafe operations in unsafe blocks.
     #[arg(long)]
     wrap_unsafe_ops: bool,
-    /// Derive custom traits on any kind of type. The <CUSTOM> value must be of the shape <REGEX>=<DERIVE> where <DERIVE> is a coma-separated list of derive macros.
+    /// Derive custom traits on any kind of type. The CUSTOM value must be of the shape REGEX=DERIVE where DERIVE is a coma-separated list of derive macros.
     #[arg(long, value_name = "CUSTOM")]
     with_derive_custom: Vec<String>,
-    /// Derive custom traits on a `struct`. The <CUSTOM> value must be of the shape <REGEX>=<DERIVE> where <DERIVE> is a coma-separated list of derive macros.
+    /// Derive custom traits on a `struct`. The CUSTOM value must be of the shape REGEX=DERIVE where DERIVE is a coma-separated list of derive macros.
     #[arg(long, value_name = "CUSTOM")]
     with_derive_custom_struct: Vec<String>,
-    /// Derive custom traits on an `enum. The <CUSTOM> value must be of the shape <REGEX>=<DERIVE> where <DERIVE> is a coma-separated list of derive macros.
+    /// Derive custom traits on an `enum. The CUSTOM value must be of the shape REGEX=DERIVE where DERIVE is a coma-separated list of derive macros.
     #[arg(long, value_name = "CUSTOM")]
     with_derive_custom_enum: Vec<String>,
-    /// Derive custom traits on a `union`. The <CUSTOM> value must be of the shape <REGEX>=<DERIVE> where <DERIVE> is a coma-separated list of derive macros.
+    /// Derive custom traits on a `union`. The CUSTOM value must be of the shape REGEX=DERIVE where DERIVE is a coma-separated list of derive macros.
     #[arg(long, value_name = "CUSTOM")]
     with_derive_custom_union: Vec<String>,
     /// Generate wrappers for `static` and `static inline` functions.

diff --git a/bindgen/ir/analysis/sizedness.rs b/bindgen/ir/analysis/sizedness.rs
@@ -52,7 +52,7 @@ pub(crate) enum SizednessResult {
     /// have an `_address` byte inserted.
     ///
     /// We don't properly handle this situation correctly right now:
-    /// https://github.com/rust-lang/rust-bindgen/issues/586
+    /// <https://github.com/rust-lang/rust-bindgen/issues/586>
     DependsOnTypeParam,
 
     /// Has some size that is known to be greater than zero. That doesn't mean

diff --git a/bindgen/ir/annotations.rs b/bindgen/ir/annotations.rs
@@ -83,7 +83,7 @@ pub(crate) struct Annotations {
     disallow_debug: bool,
     /// Manually disable deriving/implement default on this type.
     disallow_default: bool,
-    /// Whether to add a #[must_use] annotation to this type.
+    /// Whether to add a `#[must_use]` annotation to this type.
     must_use_type: bool,
     /// Visibility of struct fields. You can set this on
     /// structs (it will apply to all the fields), or individual fields.

diff --git a/bindgen/ir/function.rs b/bindgen/ir/function.rs
@@ -650,9 +650,9 @@ impl FunctionSig {
     ///
     /// For more details, see:
     ///
-    /// * https://github.com/rust-lang/rust-bindgen/issues/547,
-    /// * https://github.com/rust-lang/rust/issues/38848,
-    /// * and https://github.com/rust-lang/rust/issues/40158
+    /// * <https://github.com/rust-lang/rust-bindgen/issues/547>,
+    /// * <https://github.com/rust-lang/rust/issues/38848>,
+    /// * and <https://github.com/rust-lang/rust/issues/40158>
     pub(crate) fn function_pointers_can_derive(&self) -> bool {
         if self.argument_types.len() > RUST_DERIVE_FUNPTR_LIMIT {
             return false;

diff --git a/bindgen/ir/item.rs b/bindgen/ir/item.rs
@@ -1096,7 +1096,7 @@ impl Item {
         })
     }
 
-    /// Whether this is a #[must_use] type.
+    /// Whether this is a `#[must_use]` type.
     pub(crate) fn must_use(&self, ctx: &BindgenContext) -> bool {
         self.annotations().must_use_type() || ctx.must_use_type_by_name(self)
     }
@@ -1749,9 +1749,8 @@ impl Item {
         ret
     }
 
-    /// A named type is a template parameter, e.g., the "T" in Foo<T>. They're
-    /// always local so it's the only exception when there's no declaration for
-    /// a type.
+    /// A named type is a template parameter, e.g., the `T` in `Foo<T>`. They're always local so
+    /// it's the only exception when there's no declaration for a type.
     pub(crate) fn type_param(
         with_id: Option<ItemId>,
         location: clang::Cursor,

diff --git a/bindgen/ir/template.rs b/bindgen/ir/template.rs
@@ -77,26 +77,26 @@ use crate::clang;
 /// The following table depicts the results of each trait method when invoked on
 /// each of the declarations above:
 ///
-/// +------+----------------------+--------------------------+------------------------+----
-/// |Decl. | self_template_params | num_self_template_params | all_template_parameters| ...
-/// +------+----------------------+--------------------------+------------------------+----
-/// |Foo   | [T, U]               | 2                        | [T, U]                 | ...
-/// |Bar   | [V]                  | 1                        | [T, U, V]              | ...
-/// |Inner | []                   | 0                        | [T, U]                 | ...
-/// |Lol   | [W]                  | 1                        | [T, U, W]              | ...
-/// |Wtf   | [X]                  | 1                        | [T, U, X]              | ...
-/// |Qux   | []                   | 0                        | []                     | ...
+/// +------+----------------------+--------------------------+-------------------------+----
+/// |Decl. | self_template_params | num_self_template_params | all_template_parameters | ...
+/// +------+----------------------+--------------------------+-------------------------+----
+/// |Foo   | T, U                 | 2                        | T, U                    | ...
+/// |Bar   | V                    | 1                        | T, U, V                 | ...
+/// |Inner |                      | 0                        | T, U                    | ...
+/// |Lol   | W                    | 1                        | T, U, W                 | ...
+/// |Wtf   | X                    | 1                        | T, U, X                 | ...
+/// |Qux   |                      | 0                        |                         | ...
 /// +------+----------------------+--------------------------+------------------------+----
 ///
 /// ----+------+-----+----------------------+
 /// ... |Decl. | ... | used_template_params |
 /// ----+------+-----+----------------------+
-/// ... |Foo   | ... | [T, U]               |
-/// ... |Bar   | ... | [V]                  |
-/// ... |Inner | ... | []                   |
-/// ... |Lol   | ... | [T]                  |
-/// ... |Wtf   | ... | [T]                  |
-/// ... |Qux   | ... | []                   |
+/// ... |Foo   | ... | T, U                 |
+/// ... |Bar   | ... | V                    |
+/// ... |Inner | ... |                      |
+/// ... |Lol   | ... | T                    |
+/// ... |Wtf   | ... | T                    |
+/// ... |Qux   | ... |                      |
 /// ----+------+-----+----------------------+
 pub(crate) trait TemplateParameters: Sized {
     /// Get the set of `ItemId`s that make up this template declaration's free

diff --git a/bindgen/options/as_args.rs b/bindgen/options/as_args.rs
@@ -2,7 +2,7 @@ use std::path::PathBuf;
 
 use crate::RegexSet;
 
-/// Trait used to turn [`BindgenOptions`] fields into CLI args.
+/// Trait used to turn [`crate::BindgenOptions`] fields into CLI args.
 pub(super) trait AsArgs {
     fn as_args(&self, args: &mut Vec<String>, flag: &str);
 }
@@ -38,7 +38,7 @@ impl AsArgs for Option<String> {
     }
 }
 
-/// If the `Option` is `Some(path)`, push `flag` followed by the [`PathBuf::display`]
+/// If the `Option` is `Some(path)`, push `flag` followed by the [`std::path::Path::display`]
 /// representation of `path`.
 impl AsArgs for Option<PathBuf> {
     fn as_args(&self, args: &mut Vec<String>, flag: &str) {

diff --git a/bindgen/options/helpers.rs b/bindgen/options/helpers.rs
@@ -1,4 +1,4 @@
-/// Helper function that appends extra documentation to [`Builder`] methods that support regular
+/// Helper function that appends extra documentation to [`crate::Builder`] methods that support regular
 /// expressions in their input.
 macro_rules! regex_option {
     ($(#[$attrs:meta])* pub fn $($tokens:tt)*) => {