Skip to content

Commit fa8dd50

Browse files
pvdrzpvdrz
authored
Add docs workflow (#2493)
* Add `docs` workflow * Fix documentation warnings
1 parent 2bcff0f commit fa8dd50

File tree

10 files changed

+84
-68
lines changed

10 files changed

+84
-68
lines changed

‎.github/workflows/bindgen.yml

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -71,6 +71,23 @@ jobs:
7171
- name: Check without default features
7272
run: cargo check -p bindgen --no-default-features --features=runtime
7373

74+
docs:
75+
runs-on: ubuntu-latest
76+
env:
77+
RUSTDOCFLAGS: -D warnings
78+
steps:
79+
- uses: actions/checkout@v3
80+
81+
- name: Install stable
82+
uses: actions-rs/toolchain@v1
83+
with:
84+
profile: minimal
85+
toolchain: stable
86+
override: true
87+
88+
- name: Generate documentation
89+
run: cargo doc --document-private-items
90+
7491
quickchecking:
7592
runs-on: ubuntu-latest
7693
steps:

‎bindgen-cli/options.rs

Lines changed: 34 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -54,22 +54,22 @@ struct BindgenCommand {
5454
/// The default style of code used to generate enums.
5555
#[arg(long, value_name = "VARIANT")]
5656
default_enum_style: Option<EnumVariation>,
57-
/// Mark any enum whose name matches <REGEX> as a set of bitfield flags.
57+
/// Mark any enum whose name matches REGEX as a set of bitfield flags.
5858
#[arg(long, value_name = "REGEX")]
5959
bitfield_enum: Vec<String>,
60-
/// Mark any enum whose name matches <REGEX> as a newtype.
60+
/// Mark any enum whose name matches REGEX as a newtype.
6161
#[arg(long, value_name = "REGEX")]
6262
newtype_enum: Vec<String>,
63-
/// Mark any enum whose name matches <REGEX> as a global newtype.
63+
/// Mark any enum whose name matches REGEX as a global newtype.
6464
#[arg(long, value_name = "REGEX")]
6565
newtype_global_enum: Vec<String>,
66-
/// Mark any enum whose name matches <REGEX> as a Rust enum.
66+
/// Mark any enum whose name matches REGEX as a Rust enum.
6767
#[arg(long, value_name = "REGEX")]
6868
rustified_enum: Vec<String>,
69-
/// Mark any enum whose name matches <REGEX> as a series of constants.
69+
/// Mark any enum whose name matches REGEX as a series of constants.
7070
#[arg(long, value_name = "REGEX")]
7171
constified_enum: Vec<String>,
72-
/// Mark any enum whose name matches <regex> as a module of constants.
72+
/// Mark any enum whose name matches REGEX as a module of constants.
7373
#[arg(long, value_name = "REGEX")]
7474
constified_enum_module: Vec<String>,
7575
/// The default signed/unsigned type for C macro constants.
@@ -78,34 +78,34 @@ struct BindgenCommand {
7878
/// The default style of code used to generate typedefs.
7979
#[arg(long, value_name = "VARIANT")]
8080
default_alias_style: Option<AliasVariation>,
81-
/// Mark any typedef alias whose name matches <REGEX> to use normal type aliasing.
81+
/// Mark any typedef alias whose name matches REGEX to use normal type aliasing.
8282
#[arg(long, value_name = "REGEX")]
8383
normal_alias: Vec<String>,
84-
/// Mark any typedef alias whose name matches <REGEX> to have a new type generated for it.
84+
/// Mark any typedef alias whose name matches REGEX to have a new type generated for it.
8585
#[arg(long, value_name = "REGEX")]
8686
new_type_alias: Vec<String>,
87-
/// Mark any typedef alias whose name matches <REGEX> to have a new type with Deref and DerefMut to the inner type.
87+
/// Mark any typedef alias whose name matches REGEX to have a new type with Deref and DerefMut to the inner type.
8888
#[arg(long, value_name = "REGEX")]
8989
new_type_alias_deref: Vec<String>,
9090
/// The default style of code used to generate unions with non-Copy members. Note that ManuallyDrop was first stabilized in Rust 1.20.0.
9191
#[arg(long, value_name = "STYLE")]
9292
default_non_copy_union_style: Option<NonCopyUnionStyle>,
93-
/// Mark any union whose name matches <REGEX> and who has a non-Copy member to use a bindgen-generated wrapper for fields.
93+
/// Mark any union whose name matches REGEX and who has a non-Copy member to use a bindgen-generated wrapper for fields.
9494
#[arg(long, value_name = "REGEX")]
9595
bindgen_wrapper_union: Vec<String>,
96-
/// 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.
96+
/// 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.
9797
#[arg(long, value_name = "REGEX")]
9898
manually_drop_union: Vec<String>,
99-
/// Mark <TYPE> as hidden.
99+
/// Mark TYPE as hidden.
100100
#[arg(long, value_name = "TYPE")]
101101
blocklist_type: Vec<String>,
102-
/// Mark <FUNCTION> as hidden.
102+
/// Mark FUNCTION as hidden.
103103
#[arg(long, value_name = "FUNCTION")]
104104
blocklist_function: Vec<String>,
105-
/// Mark <ITEM> as hidden.
105+
/// Mark ITEM as hidden.
106106
#[arg(long, value_name = "ITEM")]
107107
blocklist_item: Vec<String>,
108-
/// Mark <FILE> as hidden.
108+
/// Mark FILE as hidden.
109109
#[arg(long, value_name = "FILE")]
110110
blocklist_file: Vec<String>,
111111
/// Avoid generating layout tests for any type.
@@ -144,7 +144,7 @@ struct BindgenCommand {
144144
/// Derive Ord on any type.
145145
#[arg(long)]
146146
with_derive_ord: bool,
147-
/// Avoid including doc comments in the output, see: https://github.com/rust-lang/rust-bindgen/issues/426
147+
/// Avoid including doc comments in the output, see: <https://github.com/rust-lang/rust-bindgen/issues/426>
148148
#[arg(long)]
149149
no_doc_comments: bool,
150150
/// 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 {
219219
/// Try to fit macro constants into types smaller than u32/i32
220220
#[arg(long)]
221221
fit_macro_constant_types: bool,
222-
/// Mark <TYPE> as opaque.
222+
/// Mark TYPE as opaque.
223223
#[arg(long, value_name = "TYPE")]
224224
opaque_type: Vec<String>,
225-
/// Write Rust bindings to <OUTPUT>.
225+
/// Write Rust bindings to OUTPUT.
226226
#[arg(long, short, value_name = "OUTPUT")]
227227
output: Option<String>,
228228
/// Add a raw line of Rust code at the beginning of output.
@@ -239,19 +239,19 @@ struct BindgenCommand {
239239
/// Conservatively generate inline namespaces to avoid name conflicts.
240240
#[arg(long)]
241241
conservative_inline_namespaces: bool,
242-
/// Allowlist all the free-standing functions matching <REGEX>. Other non-allowlisted functions will not be generated.
242+
/// Allowlist all the free-standing functions matching REGEX. Other non-allowlisted functions will not be generated.
243243
#[arg(long, value_name = "REGEX")]
244244
allowlist_function: Vec<String>,
245245
/// Generate inline functions.
246246
#[arg(long)]
247247
generate_inline_functions: bool,
248-
/// Only generate types matching <REGEX>. Other non-allowlisted types will not be generated.
248+
/// Only generate types matching REGEX. Other non-allowlisted types will not be generated.
249249
#[arg(long, value_name = "REGEX")]
250250
allowlist_type: Vec<String>,
251-
/// Allowlist all the free-standing variables matching <REGEX>. Other non-allowlisted variables will not be generated.
251+
/// Allowlist all the free-standing variables matching REGEX. Other non-allowlisted variables will not be generated.
252252
#[arg(long, value_name = "REGEX")]
253253
allowlist_var: Vec<String>,
254-
/// Allowlist all contents of <PATH>.
254+
/// Allowlist all contents of PATH.
255255
#[arg(long, value_name = "PATH")]
256256
allowlist_file: Vec<String>,
257257
/// Print verbose error messages.
@@ -280,25 +280,25 @@ struct BindgenCommand {
280280
/// The absolute path to the rustfmt configuration file. The configuration file will be used for formatting the bindings. This parameter sets `formatter` to `rustfmt`.
281281
#[arg(long, value_name = "PATH", conflicts_with = "no_rustfmt_bindings")]
282282
rustfmt_configuration_file: Option<String>,
283-
/// Avoid deriving PartialEq for types matching <REGEX>.
283+
/// Avoid deriving PartialEq for types matching REGEX.
284284
#[arg(long, value_name = "REGEX")]
285285
no_partialeq: Vec<String>,
286-
/// Avoid deriving Copy and Clone for types matching <REGEX>.
286+
/// Avoid deriving Copy and Clone for types matching REGEX.
287287
#[arg(long, value_name = "REGEX")]
288288
no_copy: Vec<String>,
289-
/// Avoid deriving Debug for types matching <REGEX>.
289+
/// Avoid deriving Debug for types matching REGEX.
290290
#[arg(long, value_name = "REGEX")]
291291
no_debug: Vec<String>,
292-
/// Avoid deriving/implementing Default for types matching <REGEX>.
292+
/// Avoid deriving/implementing Default for types matching REGEX.
293293
#[arg(long, value_name = "REGEX")]
294294
no_default: Vec<String>,
295-
/// Avoid deriving Hash for types matching <REGEX>.
295+
/// Avoid deriving Hash for types matching REGEX.
296296
#[arg(long, value_name = "REGEX")]
297297
no_hash: Vec<String>,
298-
/// Add #[must_use] annotation to types matching <REGEX>.
298+
/// Add `#[must_use]` annotation to types matching REGEX.
299299
#[arg(long, value_name = "REGEX")]
300300
must_use_type: Vec<String>,
301-
/// Enables detecting unexposed attributes in functions (slow). Used to generate #[must_use] annotations.
301+
/// Enables detecting unexposed attributes in functions (slow). Used to generate `#[must_use]` annotations.
302302
#[arg(long)]
303303
enable_function_attribute_detection: bool,
304304
/// Use `*const [T; size]` instead of `*const T` for C arrays
@@ -337,22 +337,22 @@ struct BindgenCommand {
337337
/// Deduplicates extern blocks.
338338
#[arg(long)]
339339
merge_extern_blocks: bool,
340-
/// 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.
340+
/// 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.
341341
#[arg(long, value_name = "OVERRIDE")]
342342
override_abi: Vec<String>,
343343
/// Wrap unsafe operations in unsafe blocks.
344344
#[arg(long)]
345345
wrap_unsafe_ops: bool,
346-
/// 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.
346+
/// 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.
347347
#[arg(long, value_name = "CUSTOM")]
348348
with_derive_custom: Vec<String>,
349-
/// 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.
349+
/// 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.
350350
#[arg(long, value_name = "CUSTOM")]
351351
with_derive_custom_struct: Vec<String>,
352-
/// 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.
352+
/// 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.
353353
#[arg(long, value_name = "CUSTOM")]
354354
with_derive_custom_enum: Vec<String>,
355-
/// 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.
355+
/// 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.
356356
#[arg(long, value_name = "CUSTOM")]
357357
with_derive_custom_union: Vec<String>,
358358
/// Generate wrappers for `static` and `static inline` functions.

‎bindgen/ir/analysis/sizedness.rs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -52,7 +52,7 @@ pub(crate) enum SizednessResult {
5252
/// have an `_address` byte inserted.
5353
///
5454
/// We don't properly handle this situation correctly right now:
55-
/// https://github.com/rust-lang/rust-bindgen/issues/586
55+
/// <https://github.com/rust-lang/rust-bindgen/issues/586>
5656
DependsOnTypeParam,
5757

5858
/// Has some size that is known to be greater than zero. That doesn't mean

‎bindgen/ir/annotations.rs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -83,7 +83,7 @@ pub(crate) struct Annotations {
8383
disallow_debug: bool,
8484
/// Manually disable deriving/implement default on this type.
8585
disallow_default: bool,
86-
/// Whether to add a #[must_use] annotation to this type.
86+
/// Whether to add a `#[must_use]` annotation to this type.
8787
must_use_type: bool,
8888
/// Visibility of struct fields. You can set this on
8989
/// structs (it will apply to all the fields), or individual fields.

‎bindgen/ir/function.rs

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -650,9 +650,9 @@ impl FunctionSig {
650650
///
651651
/// For more details, see:
652652
///
653-
/// * https://github.com/rust-lang/rust-bindgen/issues/547,
654-
/// * https://github.com/rust-lang/rust/issues/38848,
655-
/// * and https://github.com/rust-lang/rust/issues/40158
653+
/// * <https://github.com/rust-lang/rust-bindgen/issues/547>,
654+
/// * <https://github.com/rust-lang/rust/issues/38848>,
655+
/// * and <https://github.com/rust-lang/rust/issues/40158>
656656
pub(crate) fn function_pointers_can_derive(&self) -> bool {
657657
if self.argument_types.len() > RUST_DERIVE_FUNPTR_LIMIT {
658658
return false;

‎bindgen/ir/item.rs

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1096,7 +1096,7 @@ impl Item {
10961096
})
10971097
}
10981098

1099-
/// Whether this is a #[must_use] type.
1099+
/// Whether this is a `#[must_use]` type.
11001100
pub(crate) fn must_use(&self, ctx: &BindgenContext) -> bool {
11011101
self.annotations().must_use_type() || ctx.must_use_type_by_name(self)
11021102
}
@@ -1749,9 +1749,8 @@ impl Item {
17491749
ret
17501750
}
17511751

1752-
/// A named type is a template parameter, e.g., the "T" in Foo<T>. They're
1753-
/// always local so it's the only exception when there's no declaration for
1754-
/// a type.
1752+
/// A named type is a template parameter, e.g., the `T` in `Foo<T>`. They're always local so
1753+
/// it's the only exception when there's no declaration for a type.
17551754
pub(crate) fn type_param(
17561755
with_id: Option<ItemId>,
17571756
location: clang::Cursor,

‎bindgen/ir/template.rs

Lines changed: 15 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -77,26 +77,26 @@ use crate::clang;
7777
/// The following table depicts the results of each trait method when invoked on
7878
/// each of the declarations above:
7979
///
80-
/// +------+----------------------+--------------------------+------------------------+----
81-
/// |Decl. | self_template_params | num_self_template_params | all_template_parameters| ...
82-
/// +------+----------------------+--------------------------+------------------------+----
83-
/// |Foo | [T, U] | 2 | [T, U] | ...
84-
/// |Bar | [V] | 1 | [T, U, V] | ...
85-
/// |Inner | [] | 0 | [T, U] | ...
86-
/// |Lol | [W] | 1 | [T, U, W] | ...
87-
/// |Wtf | [X] | 1 | [T, U, X] | ...
88-
/// |Qux | [] | 0 | [] | ...
80+
/// +------+----------------------+--------------------------+-------------------------+----
81+
/// |Decl. | self_template_params | num_self_template_params | all_template_parameters | ...
82+
/// +------+----------------------+--------------------------+-------------------------+----
83+
/// |Foo | T, U | 2 | T, U | ...
84+
/// |Bar | V | 1 | T, U, V | ...
85+
/// |Inner | | 0 | T, U | ...
86+
/// |Lol | W | 1 | T, U, W | ...
87+
/// |Wtf | X | 1 | T, U, X | ...
88+
/// |Qux | | 0 | | ...
8989
/// +------+----------------------+--------------------------+------------------------+----
9090
///
9191
/// ----+------+-----+----------------------+
9292
/// ... |Decl. | ... | used_template_params |
9393
/// ----+------+-----+----------------------+
94-
/// ... |Foo | ... | [T, U] |
95-
/// ... |Bar | ... | [V] |
96-
/// ... |Inner | ... | [] |
97-
/// ... |Lol | ... | [T] |
98-
/// ... |Wtf | ... | [T] |
99-
/// ... |Qux | ... | [] |
94+
/// ... |Foo | ... | T, U |
95+
/// ... |Bar | ... | V |
96+
/// ... |Inner | ... | |
97+
/// ... |Lol | ... | T |
98+
/// ... |Wtf | ... | T |
99+
/// ... |Qux | ... | |
100100
/// ----+------+-----+----------------------+
101101
pub(crate) trait TemplateParameters: Sized {
102102
/// Get the set of `ItemId`s that make up this template declaration's free

‎bindgen/options/as_args.rs

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@ use std::path::PathBuf;
22

33
use crate::RegexSet;
44

5-
/// Trait used to turn [`BindgenOptions`] fields into CLI args.
5+
/// Trait used to turn [`crate::BindgenOptions`] fields into CLI args.
66
pub(super) trait AsArgs {
77
fn as_args(&self, args: &mut Vec<String>, flag: &str);
88
}
@@ -38,7 +38,7 @@ impl AsArgs for Option<String> {
3838
}
3939
}
4040

41-
/// If the `Option` is `Some(path)`, push `flag` followed by the [`PathBuf::display`]
41+
/// If the `Option` is `Some(path)`, push `flag` followed by the [`std::path::Path::display`]
4242
/// representation of `path`.
4343
impl AsArgs for Option<PathBuf> {
4444
fn as_args(&self, args: &mut Vec<String>, flag: &str) {

‎bindgen/options/helpers.rs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
/// Helper function that appends extra documentation to [`Builder`] methods that support regular
1+
/// Helper function that appends extra documentation to [`crate::Builder`] methods that support regular
22
/// expressions in their input.
33
macro_rules! regex_option {
44
($(#[$attrs:meta])* pub fn $($tokens:tt)*) => {

0 commit comments

Comments
 (0)