From 35e7078e1c6dffc3ed11c5d8a1ae16f139118686 Mon Sep 17 00:00:00 2001 From: Yuri Astrakhan Date: Mon, 2 Dec 2024 00:23:32 -0500 Subject: [PATCH] Fix some markdown First ran this ``` cargo clippy --fix --workspace --exclude bindgen-integration --exclude tests_expectations -- -W clippy::doc_markdown ``` followed by a bunch of manual fixes. --- .../tests/quickchecking/src/fuzzers.rs | 108 +++++++++--------- bindgen/callbacks.rs | 6 +- bindgen/clang.rs | 6 +- bindgen/codegen/helpers.rs | 2 +- bindgen/codegen/mod.rs | 6 +- bindgen/codegen/struct_layout.rs | 2 +- bindgen/extra_assertions.rs | 2 +- bindgen/ir/analysis/has_vtable.rs | 2 +- bindgen/ir/comp.rs | 16 +-- bindgen/ir/context.rs | 20 ++-- bindgen/ir/function.rs | 2 +- bindgen/ir/item.rs | 8 +- bindgen/ir/objc.rs | 20 ++-- bindgen/ir/template.rs | 36 +++--- bindgen/ir/traversal.rs | 2 +- bindgen/ir/ty.rs | 6 +- bindgen/ir/var.rs | 4 +- bindgen/lib.rs | 4 +- bindgen/options/cli.rs | 1 + bindgen/regex_set.rs | 4 +- 20 files changed, 128 insertions(+), 129 deletions(-) diff --git a/bindgen-tests/tests/quickchecking/src/fuzzers.rs b/bindgen-tests/tests/quickchecking/src/fuzzers.rs index fffe78f8c7..eea0393239 100644 --- a/bindgen-tests/tests/quickchecking/src/fuzzers.rs +++ b/bindgen-tests/tests/quickchecking/src/fuzzers.rs @@ -1,7 +1,7 @@ use quickcheck::{Arbitrary, Gen}; use std::fmt; -/// BaseTypeC is used in generation of C headers to represent the C language's +/// `BaseTypeC` is used in generation of C headers to represent the C language's /// primitive types as well as `void*`. #[derive(Debug, Clone)] pub struct BaseTypeC { @@ -9,7 +9,7 @@ pub struct BaseTypeC { pub def: String, } -/// TypeQualifierC is used in generation of C headers to represent qualifiers +/// `TypeQualifierC` is used in generation of C headers to represent qualifiers /// such as `const`. #[derive(Debug, Clone)] pub struct TypeQualifierC { @@ -17,7 +17,7 @@ pub struct TypeQualifierC { pub def: String, } -/// PointerLevelC is used in generation of C headers to represent number of +/// `PointerLevelC` is used in generation of C headers to represent number of /// `*` for pointer types. #[derive(Debug, Clone)] pub struct PointerLevelC { @@ -25,7 +25,7 @@ pub struct PointerLevelC { pub def: String, } -/// ArrayDimensionC is used in generation of C headers to represent number of +/// `ArrayDimensionC` is used in generation of C headers to represent number of /// `[]` used to define array types. #[derive(Debug, Clone)] pub struct ArrayDimensionC { @@ -33,7 +33,7 @@ pub struct ArrayDimensionC { pub def: String, } -/// BasicTypeDeclarationC is used in generation of C headers to represent +/// `BasicTypeDeclarationC` is used in generation of C headers to represent /// declarations outside of function pointers that take the form /// `BaseTypeC` + `TypeQualifierC` + `PointerLevelC` + `ident_id`. #[derive(Debug, Clone)] @@ -46,11 +46,11 @@ pub struct BasicTypeDeclarationC { pub pointer_level: PointerLevelC, /// The declaration's array dimension, i.e. [][][]. pub array_dimension: ArrayDimensionC, - /// The declaration's identifier, i.e. ident_N. + /// The declaration's identifier, i.e. `ident_N`. pub ident_id: String, } -/// StructDeclarationC is used in generation of C headers to represent the +/// `StructDeclarationC` is used in generation of C headers to represent the /// definition of a struct type. #[derive(Debug, Clone)] pub struct StructDeclarationC { @@ -58,11 +58,11 @@ pub struct StructDeclarationC { pub fields: DeclarationListC, /// The declaration's array dimension, i.e. [][][]. pub array_dimension: ArrayDimensionC, - /// The declaration's identifier, i.e. struct_N. + /// The declaration's identifier, i.e. `struct_N`. pub ident_id: String, } -/// UnionDeclarationC is used in generation of C headers to represent the +/// `UnionDeclarationC` is used in generation of C headers to represent the /// definition of a union type. #[derive(Debug, Clone)] pub struct UnionDeclarationC { @@ -70,11 +70,11 @@ pub struct UnionDeclarationC { pub fields: DeclarationListC, /// The declaration's array dimension, i.e. [][][]. pub array_dimension: ArrayDimensionC, - /// The declaration's identifier, i.e. union_N. + /// The declaration's identifier, i.e. `union_N`. pub ident_id: String, } -/// FunctionPointerDeclarationC is used in generation of C headers to represent +/// `FunctionPointerDeclarationC` is used in generation of C headers to represent /// the definition of a function pointer type. #[derive(Debug, Clone)] pub struct FunctionPointerDeclarationC { @@ -86,11 +86,11 @@ pub struct FunctionPointerDeclarationC { pub pointer_level: PointerLevelC, /// The function's parameters. pub params: ParameterListC, - /// The declaration's identifier, i.e. func_ptr_N. + /// The declaration's identifier, i.e. `func_ptr_N`. pub ident_id: String, } -/// FunctionPrototypeC is used in generation of C headers to represent the +/// `FunctionPrototypeC` is used in generation of C headers to represent the /// definition of a function prototype. #[derive(Debug, Clone)] pub struct FunctionPrototypeC { @@ -106,7 +106,7 @@ pub struct FunctionPrototypeC { pub ident_id: String, } -/// ParameterC is used in generation of C headers to represent the +/// `ParameterC` is used in generation of C headers to represent the /// definition function parameters. #[derive(Debug, Clone)] pub struct ParameterC { @@ -118,7 +118,7 @@ pub struct ParameterC { pub pointer_level: PointerLevelC, } -/// ParameterListC is used in generation of C headers to represent a list of +/// `ParameterListC` is used in generation of C headers to represent a list of /// definitions of function parameters. #[derive(Debug, Clone)] pub struct ParameterListC { @@ -126,7 +126,7 @@ pub struct ParameterListC { pub params: Vec, } -/// DeclarationC is used in generation of C headers to represent all supported +/// `DeclarationC` is used in generation of C headers to represent all supported /// C type declarations allowed in the generated header. #[derive(Debug, Clone)] pub enum DeclarationC { @@ -142,7 +142,7 @@ pub enum DeclarationC { VariableDecl(BasicTypeDeclarationC), } -/// DeclarationListC is used in generation of C headers to represent a list of +/// `DeclarationListC` is used in generation of C headers to represent a list of /// declarations. #[derive(Debug, Clone)] pub struct DeclarationListC { @@ -150,7 +150,7 @@ pub struct DeclarationListC { pub decls: Vec, } -/// HeaderC is used in generation of C headers to represent a collection of +/// `HeaderC` is used in generation of C headers to represent a collection of /// declarations. #[derive(Clone)] pub struct HeaderC { @@ -158,13 +158,13 @@ pub struct HeaderC { pub def: DeclarationListC, } -/// MakeUnique is used in generation of C headers to make declaration +/// `MakeUnique` is used in generation of C headers to make declaration /// identifiers unique by incorporating the `stamp` parameter into it's name. trait MakeUnique { fn make_unique(&mut self, stamp: usize); } -/// MakeUnique is used in generation of C headers to make DeclarationC +/// `MakeUnique` is used in generation of C headers to make `DeclarationC` /// identifiers unique. impl MakeUnique for DeclarationC { fn make_unique(&mut self, stamp: usize) { @@ -178,7 +178,7 @@ impl MakeUnique for DeclarationC { } } -/// A qucickcheck trait for describing how DeclarationC types can be +/// A qucickcheck trait for describing how `DeclarationC` types can be /// randomly generated and shrunk. impl Arbitrary for DeclarationC { fn arbitrary(g: &mut Gen) -> DeclarationC { @@ -197,7 +197,7 @@ impl Arbitrary for DeclarationC { } } -/// Enables to string and format for DeclarationC types. +/// Enables to string and format for `DeclarationC` types. impl fmt::Display for DeclarationC { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { match *self { @@ -210,7 +210,7 @@ impl fmt::Display for DeclarationC { } } -/// A qucickcheck trait for describing how DeclarationListC types can be +/// A qucickcheck trait for describing how `DeclarationListC` types can be /// randomly generated and shrunk. impl Arbitrary for DeclarationListC { fn arbitrary(g: &mut Gen) -> DeclarationListC { @@ -220,7 +220,7 @@ impl Arbitrary for DeclarationListC { } } -/// Enables to string and format for DeclarationListC types. +/// Enables to string and format for `DeclarationListC` types. impl fmt::Display for DeclarationListC { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { let mut display = String::new(); @@ -231,7 +231,7 @@ impl fmt::Display for DeclarationListC { } } -/// A quickcheck trait for describing how BaseTypeC types can be +/// A quickcheck trait for describing how `BaseTypeC` types can be /// randomly generated and shrunk. impl Arbitrary for BaseTypeC { fn arbitrary(g: &mut Gen) -> BaseTypeC { @@ -275,14 +275,14 @@ impl Arbitrary for BaseTypeC { } } -/// Enables to string and format for BaseTypeC types, +/// Enables to string and format for `BaseTypeC` types, impl fmt::Display for BaseTypeC { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { write!(f, "{}", self.def) } } -/// A qucickcheck trait for describing how TypeQualifierC types can be +/// A qucickcheck trait for describing how `TypeQualifierC` types can be /// randomly generated and shrunk. impl Arbitrary for TypeQualifierC { fn arbitrary(g: &mut Gen) -> TypeQualifierC { @@ -293,14 +293,14 @@ impl Arbitrary for TypeQualifierC { } } -/// Enables to string and format for TypeQualifierC types. +/// Enables to string and format for `TypeQualifierC` types. impl fmt::Display for TypeQualifierC { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { write!(f, "{}", self.def) } } -/// A qucickcheck trait for describing how PointerLevelC types can be +/// A qucickcheck trait for describing how `PointerLevelC` types can be /// randomly generated and shrunk. impl Arbitrary for PointerLevelC { fn arbitrary(g: &mut Gen) -> PointerLevelC { @@ -311,14 +311,14 @@ impl Arbitrary for PointerLevelC { } } -/// Enables to string and format for PointerLevelC types. +/// Enables to string and format for `PointerLevelC` types. impl fmt::Display for PointerLevelC { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { write!(f, "{}", self.def) } } -/// A qucickcheck trait for describing how ArrayDimensionC types can be +/// A qucickcheck trait for describing how `ArrayDimensionC` types can be /// randomly generated and shrunk. impl Arbitrary for ArrayDimensionC { fn arbitrary(g: &mut Gen) -> ArrayDimensionC { @@ -336,14 +336,14 @@ impl Arbitrary for ArrayDimensionC { } } -/// Enables to string and format for ArrayDimensionC types. +/// Enables to string and format for `ArrayDimensionC` types. impl fmt::Display for ArrayDimensionC { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { write!(f, "{}", self.def) } } -/// MakeUnique is used in generation of C headers to make BasicTypeDeclarationC +/// `MakeUnique` is used in generation of C headers to make `BasicTypeDeclarationC` /// identifiers unique. impl MakeUnique for BasicTypeDeclarationC { fn make_unique(&mut self, stamp: usize) { @@ -351,7 +351,7 @@ impl MakeUnique for BasicTypeDeclarationC { } } -/// A qucickcheck trait for describing how BasicTypeDeclarationC types can be +/// A qucickcheck trait for describing how `BasicTypeDeclarationC` types can be /// randomly generated and shrunk. impl Arbitrary for BasicTypeDeclarationC { fn arbitrary(g: &mut Gen) -> BasicTypeDeclarationC { @@ -365,7 +365,7 @@ impl Arbitrary for BasicTypeDeclarationC { } } -/// Enables to string and format for BasicTypeDeclarationC types. +/// Enables to string and format for `BasicTypeDeclarationC` types. impl fmt::Display for BasicTypeDeclarationC { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { write!( @@ -380,7 +380,7 @@ impl fmt::Display for BasicTypeDeclarationC { } } -/// MakeUnique is used in generation of C headers to make StructDeclarationC +/// `MakeUnique` is used in generation of C headers to make `StructDeclarationC` /// identifiers unique. impl MakeUnique for StructDeclarationC { fn make_unique(&mut self, stamp: usize) { @@ -388,7 +388,7 @@ impl MakeUnique for StructDeclarationC { } } -/// A qucickcheck trait for describing how StructDeclarationC types can be +/// A qucickcheck trait for describing how `StructDeclarationC` types can be /// randomly generated and shrunk. impl Arbitrary for StructDeclarationC { fn arbitrary(g: &mut Gen) -> StructDeclarationC { @@ -417,7 +417,7 @@ impl Arbitrary for StructDeclarationC { } } -/// Enables to string and format for StructDeclarationC types. +/// Enables to string and format for `StructDeclarationC` types. impl fmt::Display for StructDeclarationC { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { write!( @@ -428,7 +428,7 @@ impl fmt::Display for StructDeclarationC { } } -/// MakeUnique is used in generation of C headers to make UnionDeclarationC +/// `MakeUnique` is used in generation of C headers to make `UnionDeclarationC` /// identifiers unique. impl MakeUnique for UnionDeclarationC { fn make_unique(&mut self, stamp: usize) { @@ -436,7 +436,7 @@ impl MakeUnique for UnionDeclarationC { } } -/// A qucickcheck trait for describing how UnionDeclarationC types can be +/// A qucickcheck trait for describing how `UnionDeclarationC` types can be /// randomly generated and shrunk. impl Arbitrary for UnionDeclarationC { fn arbitrary(g: &mut Gen) -> UnionDeclarationC { @@ -465,7 +465,7 @@ impl Arbitrary for UnionDeclarationC { } } -/// Enables to string and format for UnionDeclarationC types. +/// Enables to string and format for `UnionDeclarationC` types. impl fmt::Display for UnionDeclarationC { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { write!( @@ -476,15 +476,15 @@ impl fmt::Display for UnionDeclarationC { } } -/// MakeUnique is used in generation of C headers to make -/// FunctionPointerDeclarationC identifiers unique. +/// `MakeUnique` is used in generation of C headers to make +/// `FunctionPointerDeclarationC` identifiers unique. impl MakeUnique for FunctionPointerDeclarationC { fn make_unique(&mut self, stamp: usize) { self.ident_id += &format!("_{stamp}"); } } -/// A qucickcheck trait for describing how FunctionPointerDeclarationC types can +/// A qucickcheck trait for describing how `FunctionPointerDeclarationC` types can /// be randomly generated and shrunk. impl Arbitrary for FunctionPointerDeclarationC { fn arbitrary(g: &mut Gen) -> FunctionPointerDeclarationC { @@ -498,7 +498,7 @@ impl Arbitrary for FunctionPointerDeclarationC { } } -/// Enables to string and format for FunctionPointerDeclarationC types. +/// Enables to string and format for `FunctionPointerDeclarationC` types. impl fmt::Display for FunctionPointerDeclarationC { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { write!( @@ -513,7 +513,7 @@ impl fmt::Display for FunctionPointerDeclarationC { } } -/// MakeUnique is used in generation of C headers to make FunctionPrototypeC +/// `MakeUnique` is used in generation of C headers to make `FunctionPrototypeC` /// identifiers unique. impl MakeUnique for FunctionPrototypeC { fn make_unique(&mut self, stamp: usize) { @@ -521,7 +521,7 @@ impl MakeUnique for FunctionPrototypeC { } } -/// A qucickcheck trait for describing how FunctionPrototypeC types can be +/// A qucickcheck trait for describing how `FunctionPrototypeC` types can be /// randomly generated and shrunk. impl Arbitrary for FunctionPrototypeC { fn arbitrary(g: &mut Gen) -> FunctionPrototypeC { @@ -535,7 +535,7 @@ impl Arbitrary for FunctionPrototypeC { } } -/// Enables to string and format for FunctionPrototypeC types. +/// Enables to string and format for `FunctionPrototypeC` types. impl fmt::Display for FunctionPrototypeC { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { write!( @@ -550,7 +550,7 @@ impl fmt::Display for FunctionPrototypeC { } } -/// A qucickcheck trait for describing how ParameterC types can be +/// A qucickcheck trait for describing how `ParameterC` types can be /// randomly generated and shrunk. impl Arbitrary for ParameterC { fn arbitrary(g: &mut Gen) -> ParameterC { @@ -562,7 +562,7 @@ impl Arbitrary for ParameterC { } } -/// Enables to string and format for ParameterC types. +/// Enables to string and format for `ParameterC` types. impl fmt::Display for ParameterC { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { write!( @@ -573,7 +573,7 @@ impl fmt::Display for ParameterC { } } -/// A qucickcheck trait for describing how ParameterListC types can be +/// A qucickcheck trait for describing how `ParameterListC` types can be /// randomly generated and shrunk. impl Arbitrary for ParameterListC { fn arbitrary(g: &mut Gen) -> ParameterListC { @@ -583,7 +583,7 @@ impl Arbitrary for ParameterListC { } } -/// Enables to string and format for ParameterListC types. +/// Enables to string and format for `ParameterListC` types. impl fmt::Display for ParameterListC { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { let mut display = String::new(); @@ -597,7 +597,7 @@ impl fmt::Display for ParameterListC { } } -/// A qucickcheck trait for describing how HeaderC types can be +/// A qucickcheck trait for describing how `HeaderC` types can be /// randomly generated and shrunk. impl Arbitrary for HeaderC { fn arbitrary(g: &mut Gen) -> HeaderC { @@ -609,7 +609,7 @@ impl Arbitrary for HeaderC { } } -/// Enables to string and format for HeaderC types. +/// Enables to string and format for `HeaderC` types. impl fmt::Display for HeaderC { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { let mut display = String::new(); diff --git a/bindgen/callbacks.rs b/bindgen/callbacks.rs index c824f92bc9..8a21e98dea 100644 --- a/bindgen/callbacks.rs +++ b/bindgen/callbacks.rs @@ -169,7 +169,7 @@ pub trait ParseCallbacks: fmt::Debug { // TODO add callback for ResolvedTypeRef } -/// An identifier for a discovered item. Used to identify an aliased type (see [DiscoveredItem::Alias]) +/// An identifier for a discovered item. Used to identify an aliased type (see [`DiscoveredItem::Alias`]) #[derive(Ord, PartialOrd, PartialEq, Eq, Hash, Debug, Clone, Copy)] pub struct DiscoveredItemId(usize); @@ -180,7 +180,7 @@ impl DiscoveredItemId { } } -/// Struct passed to [ParseCallbacks::new_item_found] containing information about discovered +/// Struct passed to [`ParseCallbacks::new_item_found`] containing information about discovered /// items (struct, union, and alias) #[derive(Debug, Hash, Clone, Ord, PartialOrd, Eq, PartialEq)] pub enum DiscoveredItem { @@ -262,7 +262,7 @@ pub struct ItemInfo<'a> { pub kind: ItemKind, } -/// An enum indicating the kind of item for an ItemInfo. +/// An enum indicating the kind of item for an `ItemInfo`. #[non_exhaustive] pub enum ItemKind { /// A Function diff --git a/bindgen/clang.rs b/bindgen/clang.rs index 7a21aa9f4e..0c35dbe69d 100644 --- a/bindgen/clang.rs +++ b/bindgen/clang.rs @@ -878,7 +878,7 @@ impl Cursor { /// Is the cursor's referent publicly accessible in C++? /// - /// Returns true if self.access_specifier() is `CX_CXXPublic` or + /// Returns true if `self.access_specifier()` is `CX_CXXPublic` or /// `CX_CXXInvalidAccessSpecifier`. pub(crate) fn public_accessible(&self) -> bool { let access = self.access_specifier(); @@ -957,7 +957,7 @@ impl Cursor { .collect() } - /// Obtain the real path name of a cursor of InclusionDirective kind. + /// Obtain the real path name of a cursor of `InclusionDirective` kind. /// /// Returns None if the cursor does not include a file, otherwise the file's full name pub(crate) fn get_included_file_name(&self) -> Option { @@ -1051,7 +1051,7 @@ impl ClangToken { c_str.to_bytes() } - /// Converts a ClangToken to a `cexpr` token if possible. + /// Converts a `ClangToken` to a `cexpr` token if possible. pub(crate) fn as_cexpr_token(&self) -> Option { use cexpr::token; diff --git a/bindgen/codegen/helpers.rs b/bindgen/codegen/helpers.rs index c572b8887f..1827705433 100644 --- a/bindgen/codegen/helpers.rs +++ b/bindgen/codegen/helpers.rs @@ -76,7 +76,7 @@ pub(crate) mod attributes { } /// The `ffi_safe` argument should be true if this is a type that the user might -/// reasonably use, e.g. not struct padding, where the __BindgenOpaqueArray is +/// reasonably use, e.g. not struct padding, where the `__BindgenOpaqueArray` is /// just noise. /// TODO: Should this be `MaybeUninit`, since padding bytes are effectively /// uninitialized? diff --git a/bindgen/codegen/mod.rs b/bindgen/codegen/mod.rs index 94f65669bd..574b2def09 100644 --- a/bindgen/codegen/mod.rs +++ b/bindgen/codegen/mod.rs @@ -3161,7 +3161,7 @@ impl Method { pub enum EnumVariation { /// The code for this enum will use a Rust enum. Note that creating this in unsafe code /// (including FFI) with an invalid value will invoke undefined behaviour, whether or not - /// its marked as non_exhaustive. + /// its marked as `#[non_exhaustive]`. Rust { /// Indicates whether the generated struct should be `#[non_exhaustive]` non_exhaustive: bool, @@ -3953,7 +3953,7 @@ pub enum AliasVariation { TypeAlias, /// Create a new type by wrapping the old type in a struct and using #[repr(transparent)] NewType, - /// Same as NewStruct but also impl Deref to be able to use the methods of the wrapped type + /// Same as `NewType` but also impl Deref to be able to use the methods of the wrapped type NewTypeDeref, } @@ -4156,7 +4156,7 @@ where /// implementations that need to convert another thing into a Rust type or /// opaque blob in a nested manner should also use fallible trait methods and /// propagate failure up the stack. Only infallible functions and methods like -/// CodeGenerator implementations should use the infallible +/// `CodeGenerator` implementations should use the infallible /// `ToRustTyOrOpaque`. The further out we push error recovery, the more likely /// we are to get a usable `Layout` even if we can't generate an equivalent Rust /// type for a C++ construct. diff --git a/bindgen/codegen/struct_layout.rs b/bindgen/codegen/struct_layout.rs index 88b250cf35..f7f66373fb 100644 --- a/bindgen/codegen/struct_layout.rs +++ b/bindgen/codegen/struct_layout.rs @@ -414,7 +414,7 @@ impl<'a> StructLayoutTracker<'a> { /// Returns whether the new field is known to merge with a bitfield. /// - /// This is just to avoid doing the same check also in pad_field. + /// This is just to avoid doing the same check also in `pad_field`. fn align_to_latest_field(&mut self, new_field_layout: Layout) -> bool { if self.is_packed { // Skip to align fields when packed. diff --git a/bindgen/extra_assertions.rs b/bindgen/extra_assertions.rs index fbddad7825..8526fd42d2 100644 --- a/bindgen/extra_assertions.rs +++ b/bindgen/extra_assertions.rs @@ -2,7 +2,7 @@ //! and/or CI when the `__testing_only_extra_assertions` feature is enabled. /// Simple macro that forwards to assert! when using -/// __testing_only_extra_assertions. +/// `__testing_only_extra_assertions`. macro_rules! extra_assert { ( $cond:expr ) => { if cfg!(feature = "__testing_only_extra_assertions") { diff --git a/bindgen/ir/analysis/has_vtable.rs b/bindgen/ir/analysis/has_vtable.rs index 0953df6eba..3ff64a6d2b 100644 --- a/bindgen/ir/analysis/has_vtable.rs +++ b/bindgen/ir/analysis/has_vtable.rs @@ -223,7 +223,7 @@ impl<'ctx> From> for HashMap { /// vtable during codegen. /// /// This is not for _computing_ whether the thing has a vtable, it is for -/// looking up the results of the HasVtableAnalysis's computations for a +/// looking up the results of the `HasVtableAnalysis`'s computations for a /// specific thing. pub(crate) trait HasVtable { /// Return `true` if this thing has vtable, `false` otherwise. diff --git a/bindgen/ir/comp.rs b/bindgen/ir/comp.rs index a978af581f..1dd074ba4d 100644 --- a/bindgen/ir/comp.rs +++ b/bindgen/ir/comp.rs @@ -1017,6 +1017,7 @@ pub(crate) struct CompInfo { /// The inner types that were declared inside this class, in something like: /// + /// ```c++ /// class Foo { /// typedef int FooTy; /// struct Bar { @@ -1025,6 +1026,7 @@ pub(crate) struct CompInfo { /// } /// /// static Foo::Bar const = {3}; + /// ``` inner_types: Vec, /// Set of static constants declared inside this class. @@ -1043,7 +1045,7 @@ pub(crate) struct CompInfo { has_nonempty_base: bool, /// If this type has a template parameter which is not a type (e.g.: a - /// size_t) + /// `size_t`) has_non_type_template_params: bool, /// Whether this type has a bit field member whose width couldn't be @@ -1056,7 +1058,7 @@ pub(crate) struct CompInfo { /// Used to know if we've found an opaque attribute that could cause us to /// generate a type with invalid layout. This is explicitly used to avoid us - /// generating bad alignments when parsing types like max_align_t. + /// generating bad alignments when parsing types like `max_align_t`. /// /// It's not clear what the behavior should be here, if generating the item /// and pray, or behave as an opaque type. @@ -1098,7 +1100,7 @@ impl CompInfo { /// /// If we're a union without known layout, we try to compute it from our /// members. This is not ideal, but clang fails to report the size for these - /// kind of unions, see test/headers/template_union.hpp + /// kind of unions, see `test/headers/template_union.hpp` pub(crate) fn layout(&self, ctx: &BindgenContext) -> Option { // We can't do better than clang here, sorry. if self.kind == CompKind::Struct { @@ -1213,7 +1215,7 @@ impl CompInfo { } /// Do we see a virtual function during parsing? - /// Get the has_own_virtual_method boolean. + /// Get the `has_own_virtual_method` boolean. pub(crate) fn has_own_virtual_method(&self) -> bool { self.has_own_virtual_method } @@ -1708,12 +1710,12 @@ impl CompInfo { /// Returns whether the current union can be represented as a Rust `union` /// /// Requirements: - /// 1. Current RustTarget allows for `untagged_union` - /// 2. Each field can derive `Copy` or we use ManuallyDrop. + /// 1. Current `RustTarget` allows for `untagged_union` + /// 2. Each field can derive `Copy` or we use `ManuallyDrop`. /// 3. It's not zero-sized. /// /// Second boolean returns whether all fields can be copied (and thus - /// ManuallyDrop is not needed). + /// `ManuallyDrop` is not needed). pub(crate) fn is_rust_union( &self, ctx: &BindgenContext, diff --git a/bindgen/ir/context.rs b/bindgen/ir/context.rs index fe97a8c540..9bc13de63d 100644 --- a/bindgen/ir/context.rs +++ b/bindgen/ir/context.rs @@ -310,7 +310,7 @@ enum TypeKey { /// A context used during parsing and generation of structs. #[derive(Debug)] pub(crate) struct BindgenContext { - /// The map of all the items parsed so far, keyed off ItemId. + /// The map of all the items parsed so far, keyed off `ItemId`. items: Vec>, /// Clang USR to type map. This is needed to be able to associate types with @@ -330,7 +330,7 @@ pub(crate) struct BindgenContext { /// Current module being traversed. current_module: ModuleId, - /// A HashMap keyed on a type definition, and whose value is the parent ID + /// A `HashMap` keyed on a type definition, and whose value is the parent ID /// of the declaration. /// /// This is used to handle the cases where the semantic and the lexical @@ -346,7 +346,7 @@ pub(crate) struct BindgenContext { /// This means effectively, that a type has a potential ID before knowing if /// it's a correct type. But that's not important in practice. /// - /// We could also use the `types` HashMap, but my intention with it is that + /// We could also use the `types` `HashMap`, but my intention with it is that /// only valid types and declarations end up there, and this could /// potentially break that assumption. currently_parsed_types: Vec, @@ -355,7 +355,7 @@ pub(crate) struct BindgenContext { /// hard errors while parsing duplicated macros, as well to allow macro /// expression parsing. /// - /// This needs to be an std::HashMap because the cexpr API requires it. + /// This needs to be an `std::HashMap` because the `cexpr` API requires it. parsed_macros: StdHashMap, cexpr::expr::EvalResult>, /// A map with all include locations. @@ -623,7 +623,7 @@ If you encounter an error missing from this list, please file an issue or a PR!" self.target_info.triple.starts_with("wasm32-") } - /// Creates a timer for the current bindgen phase. If time_phases is `true`, + /// Creates a timer for the current bindgen phase. If `time_phases` is `true`, /// the timer will print to stderr when it is dropped, otherwise it will do /// nothing. pub(crate) fn timer<'a>(&self, name: &'a str) -> Timer<'a> { @@ -1219,7 +1219,7 @@ If you encounter an error missing from this list, please file an issue or a PR!" /// When the `__testing_only_extra_assertions` feature is enabled, this /// function walks the IR graph and asserts that we do not have any edges - /// referencing an ItemId for which we do not have an associated IR item. + /// referencing an `ItemId` for which we do not have an associated IR item. fn assert_no_dangling_references(&self) { if cfg!(feature = "__testing_only_extra_assertions") { for _ in self.assert_no_dangling_item_traversal() { @@ -1506,7 +1506,7 @@ If you encounter an error missing from this list, please file an issue or a PR!" /// correct type definition afterwards. /// /// TODO(emilio): We could consider doing this only when - /// declaration.lexical_parent() != definition.lexical_parent(), but it's + /// `declaration.lexical_parent() != definition.lexical_parent()`, but it's /// not sure it's worth it. pub(crate) fn add_semantic_parent( &mut self, @@ -1593,7 +1593,7 @@ If you encounter an error missing from this list, please file an issue or a PR!" /// function template declarations(!?!??!). /// /// The only way to do this is manually inspecting the AST and looking for - /// TypeRefs and TemplateRefs inside. This, unfortunately, doesn't work for + /// `TypeRefs` and `TemplateRefs` inside. This, unfortunately, doesn't work for /// more complex cases, see the comment on the assertion below. /// /// To add insult to injury, the AST itself has structure that doesn't make @@ -2297,7 +2297,7 @@ If you encounter an error missing from this list, please file an issue or a PR!" (module_name, kind) } - /// Given a CXCursor_Namespace cursor, return the item ID of the + /// Given a `CXCursor_Namespace` cursor, return the item ID of the /// corresponding module, or create one on the fly. pub(crate) fn module(&mut self, cursor: Cursor) -> ModuleId { use clang_sys::*; @@ -2806,7 +2806,7 @@ If you encounter an error missing from this list, please file an issue or a PR!" !self.cannot_derive_hash.as_ref().unwrap().contains(&id) } - /// Compute whether we can derive PartialOrd, PartialEq or Eq. + /// Compute whether we can derive `PartialOrd`, `PartialEq` or `Eq`. fn compute_cannot_derive_partialord_partialeq_or_eq(&mut self) { let _t = self.timer("compute_cannot_derive_partialord_partialeq_or_eq"); assert!(self.cannot_derive_partialeq_or_partialord.is_none()); diff --git a/bindgen/ir/function.rs b/bindgen/ir/function.rs index 6fcb8d1fbb..6da986e2d9 100644 --- a/bindgen/ir/function.rs +++ b/bindgen/ir/function.rs @@ -82,7 +82,7 @@ pub(crate) struct Function { /// The mangled name, that is, the symbol. mangled_name: Option, - /// The link name. If specified, overwrite mangled_name. + /// The link name. If specified, overwrite `mangled_name`. link_name: Option, /// The ID pointing to the current function signature. diff --git a/bindgen/ir/item.rs b/bindgen/ir/item.rs index 010297615d..0717f3e877 100644 --- a/bindgen/ir/item.rs +++ b/bindgen/ir/item.rs @@ -44,7 +44,7 @@ pub(crate) trait ItemCanonicalName { /// The same, but specifies the path that needs to be followed to reach an item. /// -/// To contrast with canonical_name, here's an example: +/// To contrast with `canonical_name`, here's an example: /// /// ```c++ /// namespace foo { @@ -375,7 +375,7 @@ pub(crate) struct Item { /// The item's local ID, unique only amongst its siblings. Only used for /// anonymous items. /// - /// Lazily initialized in local_id(). + /// Lazily initialized in `local_id()`. /// /// Note that only structs, unions, and enums get a local type ID. In any /// case this is an implementation detail. @@ -668,7 +668,7 @@ impl Item { } } - /// Take out item NameOptions + /// Take out item `NameOptions` pub(crate) fn name<'a>( &'a self, ctx: &'a BindgenContext, @@ -716,7 +716,7 @@ impl Item { s } - /// Helper function for full_disambiguated_name + /// Helper function for `full_disambiguated_name` fn push_disambiguated_name( &self, ctx: &BindgenContext, diff --git a/bindgen/ir/objc.rs b/bindgen/ir/objc.rs index 81560da4d1..d413d6bb95 100644 --- a/bindgen/ir/objc.rs +++ b/bindgen/ir/objc.rs @@ -17,20 +17,20 @@ use clang_sys::CXCursor_ObjCSuperClassRef; use clang_sys::CXCursor_TemplateTypeParameter; use proc_macro2::{Ident, Span, TokenStream}; -/// Objective C interface as used in TypeKind +/// Objective-C interface as used in `TypeKind` /// -/// Also protocols and categories are parsed as this type +/// Also, protocols and categories are parsed as this type #[derive(Debug)] pub(crate) struct ObjCInterface { /// The name - /// like, NSObject + /// like, `NSObject` name: String, category: Option, is_protocol: bool, - /// The list of template names almost always, ObjectType or KeyType + /// The list of template names almost always, `ObjectType` or `KeyType` pub(crate) template_names: Vec, /// The list of protocols that this interface conforms to. @@ -53,7 +53,7 @@ pub(crate) struct ObjCMethod { name: String, /// Method name as converted to rust - /// like, dataWithBytes_length_ + /// like, `dataWithBytes_length`_ rust_name: String, signature: FunctionSig, @@ -77,14 +77,14 @@ impl ObjCInterface { } /// The name - /// like, NSObject + /// like, `NSObject` pub(crate) fn name(&self) -> &str { self.name.as_ref() } /// Formats the name for rust - /// Can be like NSObject, but with categories might be like NSObject_NSCoderMethods - /// and protocols are like PNSObject + /// Can be like `NSObject`, but with categories might be like `NSObject_NSCoderMethods` + /// and protocols are like `PNSObject` pub(crate) fn rust_name(&self) -> String { if let Some(ref cat) = self.category { format!("{}_{cat}", self.name()) @@ -227,12 +227,12 @@ impl ObjCMethod { } /// Method name as converted to rust - /// like, dataWithBytes_length_ + /// like, `dataWithBytes_length`_ pub(crate) fn rust_name(&self) -> &str { self.rust_name.as_ref() } - /// Returns the methods signature as FunctionSig + /// Returns the methods signature as `FunctionSig` pub(crate) fn signature(&self) -> &FunctionSig { &self.signature } diff --git a/bindgen/ir/template.rs b/bindgen/ir/template.rs index 2783b414d8..7f3667879d 100644 --- a/bindgen/ir/template.rs +++ b/bindgen/ir/template.rs @@ -77,27 +77,23 @@ 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 | ... | | -/// ----+------+-----+----------------------+ +/// | Decl. | used_template_params | +/// |-------|----------------------| +/// | 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 /// template parameters. diff --git a/bindgen/ir/traversal.rs b/bindgen/ir/traversal.rs index ccf3af9a25..01f3a8bd50 100644 --- a/bindgen/ir/traversal.rs +++ b/bindgen/ir/traversal.rs @@ -235,7 +235,7 @@ pub(crate) fn codegen_edges(ctx: &BindgenContext, edge: Edge) -> bool { /// outgoing edges might not have been fully traversed yet) in an active /// traversal. pub(crate) trait TraversalStorage<'ctx> { - /// Construct a new instance of this TraversalStorage, for a new traversal. + /// Construct a new instance of this `TraversalStorage`, for a new traversal. fn new(ctx: &'ctx BindgenContext) -> Self; /// Add the given item to the storage. If the item has never been seen diff --git a/bindgen/ir/ty.rs b/bindgen/ir/ty.rs index 98df40d2b3..cd9a9a1edf 100644 --- a/bindgen/ir/ty.rs +++ b/bindgen/ir/ty.rs @@ -275,7 +275,7 @@ impl Type { } } - /// See safe_canonical_type. + /// See [`Self::safe_canonical_type`]. pub(crate) fn canonical_type<'tr>( &'tr self, ctx: &'tr BindgenContext, @@ -623,7 +623,7 @@ pub(crate) enum TypeKind { /// A pointer to an Apple block. BlockPointer(TypeId), - /// A reference to a type, as in: int& foo(). + /// A reference to a type, as in: int& `foo()`. Reference(TypeId), /// An instantiation of an abstract template definition with a set of @@ -634,7 +634,7 @@ pub(crate) enum TypeKind { /// itself, and postpones its resolution. /// /// These are gone in a phase after parsing where these are mapped to - /// already known types, and are converted to ResolvedTypeRef. + /// already known types, and are converted to `ResolvedTypeRef`. /// /// see tests/headers/typeref.hpp to see somewhere where this is a problem. UnresolvedTypeRef(clang::Type, Cursor, /* parent_id */ Option), diff --git a/bindgen/ir/var.rs b/bindgen/ir/var.rs index fa6930ec14..4f61448fea 100644 --- a/bindgen/ir/var.rs +++ b/bindgen/ir/var.rs @@ -149,8 +149,8 @@ fn default_macro_constant_type(ctx: &BindgenContext, value: i64) -> IntKind { } } -/// Parses tokens from a CXCursor_MacroDefinition pointing into a function-like -/// macro, and calls the func_macro callback. +/// Parses tokens from a `CXCursor_MacroDefinition` pointing into a function-like +/// macro, and calls the `func_macro` callback. fn handle_function_macro( cursor: &clang::Cursor, callbacks: &dyn crate::callbacks::ParseCallbacks, diff --git a/bindgen/lib.rs b/bindgen/lib.rs index 58e1da8665..c9b529ac66 100644 --- a/bindgen/lib.rs +++ b/bindgen/lib.rs @@ -1212,7 +1212,7 @@ fn get_target_dependent_env_var( env_var(parse_callbacks, var).ok() } -/// A ParseCallbacks implementation that will act on file includes by echoing a rerun-if-changed +/// A `ParseCallbacks` implementation that will act on file includes by echoing a rerun-if-changed /// line and on env variable usage by echoing a rerun-if-env-changed line /// /// When running inside a `build.rs` script, this can be used to make cargo invalidate the @@ -1278,7 +1278,7 @@ impl callbacks::ParseCallbacks for CargoCallbacks { } } -/// Test command_line_flag function. +/// Test `command_line_flag` function. #[test] fn commandline_flag_unit_test_function() { //Test 1 diff --git a/bindgen/options/cli.rs b/bindgen/options/cli.rs index 29b4413b1b..9d5cea3dc6 100644 --- a/bindgen/options/cli.rs +++ b/bindgen/options/cli.rs @@ -143,6 +143,7 @@ fn parse_custom_attribute( override_usage = "bindgen
-- ...", trailing_var_arg = true )] +#[allow(clippy::doc_markdown)] struct BindgenCommand { /// C or C++ header file. header: String, diff --git a/bindgen/regex_set.rs b/bindgen/regex_set.rs index 3b6aa34101..32279557b5 100644 --- a/bindgen/regex_set.rs +++ b/bindgen/regex_set.rs @@ -49,7 +49,7 @@ impl RegexSet { }) } - /// Construct a RegexSet from the set of entries we've accumulated. + /// Construct a `RegexSet` from the set of entries we've accumulated. /// /// Must be called before calling `matches()`, or it will always return /// false. @@ -60,7 +60,7 @@ impl RegexSet { } #[cfg(all(feature = "__cli", feature = "experimental"))] - /// Construct a RegexSet from the set of entries we've accumulated and emit diagnostics if the + /// Construct a `RegexSet` from the set of entries we've accumulated and emit diagnostics if the /// name of the regex set is passed to it. /// /// Must be called before calling `matches()`, or it will always return