From 493ceaf98232c4de9f7ba51a46a48478acd34b39 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Carlos=20L=C3=B3pez?= Date: Fri, 22 Nov 2024 18:47:47 +0100 Subject: [PATCH] acpi: fix doc warnings and add missing links When generating the documentation, cargo doc would emit some warnings regarding redundant and broken links, so fix them. Also add some convenient links which were missing. --- acpi/src/lib.rs | 38 +++++++++++++++++--------------------- 1 file changed, 17 insertions(+), 21 deletions(-) diff --git a/acpi/src/lib.rs b/acpi/src/lib.rs index f59cef00..ea00f382 100644 --- a/acpi/src/lib.rs +++ b/acpi/src/lib.rs @@ -20,14 +20,14 @@ //! default configuration of the crate. //! //! ### Usage -//! To use the library, you will need to provide an implementation of the `AcpiHandler` trait, which allows the +//! To use the library, you will need to provide an implementation of the [`AcpiHandler`] trait, which allows the //! library to make requests such as mapping a particular region of physical memory into the virtual address space. //! -//! You then need to construct an instance of `AcpiTables`, which can be done in a few ways depending on how much +//! You then need to construct an instance of [`AcpiTables`], which can be done in a few ways depending on how much //! information you have: -//! * Use `AcpiTables::from_rsdp` if you have the physical address of the RSDP -//! * Use `AcpiTables::from_rsdt` if you have the physical address of the RSDT/XSDT -//! * Use `AcpiTables::search_for_rsdp_bios` if you don't have the address of either, but **you know you are +//! * Use [`AcpiTables::from_rsdp`] if you have the physical address of the RSDP +//! * Use [`AcpiTables::from_rsdt`] if you have the physical address of the RSDT/XSDT +//! * Use [`AcpiTables::search_for_rsdp_bios`] if you don't have the address of either, but **you know you are //! running on BIOS, not UEFI** //! //! `AcpiTables` stores the addresses of all of the tables detected on a platform. The SDTs are parsed by this @@ -35,13 +35,12 @@ //! `aml`. //! //! To gather information out of the static tables, a few of the types you should take a look at are: -//! - [`PlatformInfo`](crate::platform::PlatformInfo) parses the FADT and MADT to create a nice view of the -//! processor topology and interrupt controllers on `x86_64`, and the interrupt controllers on other platforms. -//! `AcpiTables::platform_info` is a convenience method for constructing a `PlatformInfo`. -//! - [`HpetInfo`](crate::hpet::HpetInfo) parses the HPET table and tells you how to configure the High -//! Precision Event Timer. -//! - [`PciConfigRegions`](crate::mcfg::PciConfigRegions) parses the MCFG and tells you how PCIe configuration -//! space is mapped into physical memory. +//! - [`PlatformInfo`] parses the FADT and MADT to create a nice view of the processor topology and interrupt +//! controllers on `x86_64`, and the interrupt controllers on other platforms. +//! [`AcpiTables::platform_info`] is a convenience method for constructing a `PlatformInfo`. +//! - [`HpetInfo`] parses the HPET table and tells you how to configure the High Precision Event Timer. +//! - [`PciConfigRegions`] parses the MCFG and tells you how PCIe configuration space is mapped into physical +//! memory. /* * Contributing notes (you may find these useful if you're new to contributing to the library): @@ -210,8 +209,7 @@ where } /// Search for the RSDP on a BIOS platform. This accesses BIOS-specific memory locations and will probably not - /// work on UEFI platforms. See [Rsdp::search_for_rsdp_bios](rsdp_search::Rsdp::search_for_rsdp_bios) for - /// details. + /// work on UEFI platforms. See [`Rsdp::search_for_on_bios`] for details. pub unsafe fn search_for_rsdp_bios(handler: H) -> AcpiResult { let rsdp_mapping = unsafe { Rsdp::search_for_on_bios(handler.clone())? }; // Safety: RSDP has been validated from `Rsdp::search_for_on_bios` @@ -355,19 +353,17 @@ where SsdtIterator { tables_phys_ptrs: self.tables_phys_ptrs(), handler: self.handler.clone() } } - /// Convenience method for contructing a [`PlatformInfo`](crate::platform::PlatformInfo). This is one of the - /// first things you should usually do with an `AcpiTables`, and allows to collect helpful information about - /// the platform from the ACPI tables. + /// Convenience method for contructing a [`PlatformInfo`]. This is one of the first things you should usually do + /// with an `AcpiTables`, and allows to collect helpful information about the platform from the ACPI tables. /// - /// Like `platform_info_in`, but uses the global allocator. + /// Like [`platform_info_in`](Self::platform_info_in), but uses the global allocator. #[cfg(feature = "alloc")] pub fn platform_info(&self) -> AcpiResult> { PlatformInfo::new(self) } - /// Convenience method for contructing a [`PlatformInfo`](crate::platform::PlatformInfo). This is one of the - /// first things you should usually do with an `AcpiTables`, and allows to collect helpful information about - /// the platform from the ACPI tables. + /// Convenience method for contructing a [`PlatformInfo`]. This is one of the first things you should usually do + /// with an `AcpiTables`, and allows to collect helpful information about the platform from the ACPI tables. #[cfg(feature = "allocator_api")] pub fn platform_info_in(&self, allocator: A) -> AcpiResult> where