Improve documentation some more

This patch improves the documentation a bit more.

Signed-off-by: Daniel Müller <[email protected]>

src/normalize/meta.rs

@@ -7,6 +7,8 @@ type BuildId = Vec<u8>;
 
 /// Meta information about an APK.
 ///
+/// This type is used in the [`UserMeta::Apk`] variant.
+///
 /// The corresponding file offset is normalized only to the APK container, not
 /// any potential internal ELF files. Use the
 /// [`Apk`][crate::symbolize::Source::Apk] symbolization source in order to
@@ -47,6 +49,8 @@ pub struct Apk {
 
 
 /// Meta information about an ELF file (executable, shared object, ...).
+///
+/// This type is used in the [`UserMeta::Elf`] variant.
 #[derive(Clone, Debug, PartialEq)]
 pub struct Elf {
     /// The canonical absolute path to the ELF file, including its name.
@@ -60,8 +64,12 @@ pub struct Elf {
 
 
 /// Meta information about an address that could not be determined to be
-/// belonging to a specific component. Such an address will be reported
-/// in non-normalized form (as provided by the user).
+/// belonging to a specific component.
+///
+/// This type is used in the [`UserMeta::Unknown`] variant.
+///
+/// An unknown address will be reported in non-normalized form (i.e., as
+/// provided as input by the user).
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct Unknown {
     /// The struct is non-exhaustive and open to extension.

src/normalize/mod.rs

@@ -1,13 +1,21 @@
 //! Functionality for address normalization.
 //!
-//! Address normalization is one step of address symbolization: before an
-//! address as captured in a process can be looked up in a file, it needs to be
-//! converted into an address as it will be used inside the file. E.g.,
-//! addresses in a shared object (or any position independent binary) may be
-//! relative to that file. When such a shared object is loaded into a process,
-//! it is relocated. Normalization removes this relocation information and
-//! similar adjustments made by the system (e.g., by address space layout
-//! randomization).
+//! Address normalization is one step of address symbolization. Typically only
+//! used internally, it is also made accessible for users to enable remote
+//! symbolization work flows. Remote symbolization refers to performing
+//! symbolization on a system other than where the "raw" addresses were
+//! originally captured. This is useful when working with embedded or locked
+//! down systems, for example, where files necessary to perform the
+//! symbolization are not available or not accessible.
+//!
+//! In such a setting address normalization would happen on the embedded device.
+//! The result of this normalization would then be transferred to another one
+//! that actually performs the symbolization.
+//!
+//! The [output][UserOutput] of address normalization is a set of file offsets
+//! along with meta data. The meta data is expected to contain sufficient
+//! information to identify the symbolization source to use (e.g., the ELF file
+//! with symbols) on the symbolizing system.
 //!
 //! ```no_run
 //! use blazesym::normalize::Normalizer;
@@ -41,6 +49,10 @@ pub use meta::Unknown;
 pub use meta::UserMeta;
 pub use normalizer::Builder;
 pub use normalizer::Normalizer;
+// For reasons unknown, we need to `pub use` this type here or the documentation
+// will not resolve links. See https://github.com/rust-lang/rust/issues/116854
+#[doc(hidden)]
+pub use normalizer::Output;
 pub use user::UserOutput;
 
 pub(crate) use user::create_apk_elf_path;

src/normalize/normalizer.rs

@@ -23,7 +23,8 @@ pub struct Output<M> {
     ///
     /// A file offset is one as it would appear in a binary or debug symbol
     /// file, i.e., one excluding any relocations. The data reported here can be
-    /// used with the [`symbolize::Input::FileOffset`] variant.
+    /// used with the [`symbolize::Input::FileOffset`][crate::symbolize::Input::FileOffset]
+    /// variant.
     pub outputs: Vec<(u64, usize)>,
     /// Meta information about the normalized outputs.
     pub meta: Vec<M>,
@@ -89,7 +90,7 @@ impl Normalizer {
         Builder::default()
     }
 
-    /// Normalize `addresses` belonging to a process.
+    /// Normalize addresses belonging to a process.
     ///
     /// Normalize all `addrs` in a given process. The `addrs` array has
     /// to be sorted in ascending order or an error will be returned. By
@@ -117,7 +118,7 @@ impl Normalizer {
     }
 
 
-    /// Normalize `addresses` belonging to a process.
+    /// Normalize addresses belonging to a process.
     ///
     /// Normalize all `addrs` in a given process. Contrary to
     /// [`Normalizer::normalize_user_addrs_sorted`], the provided `addrs` array

src/symbolize/source.rs

@@ -10,6 +10,8 @@ use super::Symbolizer;
 
 
 /// A single APK file.
+///
+/// This type is used in the [`Source::Apk`] variant.
 #[derive(Clone)]
 pub struct Apk {
     /// The path to an APK file.
@@ -48,6 +50,8 @@ impl Debug for Apk {
 
 
 /// A single ELF file.
+///
+/// This type is used in the [`Source::Elf`] variant.
 #[derive(Clone)]
 pub struct Elf {
     /// The path to an ELF file.
@@ -89,7 +93,9 @@ impl Debug for Elf {
 }
 
 
-/// Linux Kernel's binary image and a copy of /proc/kallsyms
+/// Linux Kernel's binary image and a copy of `/proc/kallsyms`.
+///
+/// This type is used in the [`Source::Kernel`] variant.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct Kernel {
     /// The path of a kallsyms copy.
@@ -121,9 +127,12 @@ impl From<Kernel> for Source<'static> {
 
 /// Configuration for process based address symbolization.
 ///
+/// This type is used in the [`Source::Process`] variant.
+///
 /// The corresponding addresses supplied to [`Symbolizer::symbolize`] are
-/// expected to be absolute addresses as valid within the process identified
-/// by the [`pid`][Process::pid] member.
+/// expected to be absolute addresses
+/// ([`Input::AbsAddr`][crate::symbolize::Input::AbsAddr]) as valid within the
+/// process identified by the [`pid`][Process::pid] member.
 #[derive(Clone)]
 pub struct Process {
     /// The referenced process' ID.
@@ -165,6 +174,8 @@ impl From<Process> for Source<'static> {
 
 
 /// Enumeration of supported Gsym sources.
+///
+/// This type is used in the [`Source::Gsym`] variant.
 #[derive(Clone, Debug)]
 pub enum Gsym<'dat> {
     /// "Raw" Gsym data.