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.

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

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<String> {
@@ -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<cexpr::token::Token> {
         use cexpr::token;
 

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?

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.

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.

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") {

bindgen/ir/analysis/has_vtable.rs

@@ -223,7 +223,7 @@ impl<'ctx> From<HasVtableAnalysis<'ctx>> for HashMap<ItemId, HasVtableResult> {
 /// 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.

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<TypeId>,
 
     /// 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<Layout> {
         // 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,

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<Option<Item>>,
 
     /// 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<PartialType>,
@@ -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<Vec<u8>, 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());

bindgen/ir/function.rs

@@ -82,7 +82,7 @@ pub(crate) struct Function {
     /// The mangled name, that is, the symbol.
     mangled_name: Option<String>,
 
-    /// The link name. If specified, overwrite mangled_name.
+    /// The link name. If specified, overwrite `mangled_name`.
     link_name: Option<String>,
 
     /// The ID pointing to the current function signature.

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,

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<String>,
 
     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<String>,
 
     /// 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
     }