read: add DwarfPackageSections::borrow

Also replace Dwarf::borrow with DwarfSections::borrow
for consistency.

crates/examples/src/bin/simple.rs

@@ -29,7 +29,7 @@ fn dump_file(object: &object::File, endian: gimli::RunTimeEndian) -> Result<(),
     };
 
     // Load all of the sections.
-    let dwarf_cow = gimli::Dwarf::load(&load_section)?;
+    let dwarf_cow = gimli::DwarfSections::load(&load_section)?;
 
     // Borrow a `Cow<[u8]>` to create an `EndianSlice`.
     let borrow_section: &dyn for<'a> Fn(
@@ -38,6 +38,7 @@ fn dump_file(object: &object::File, endian: gimli::RunTimeEndian) -> Result<(),
         &|section| gimli::EndianSlice::new(section, endian);
 
     // Create `EndianSlice`s for all of the sections.
+    // Alternatively, we could have used `Dwarf::load` with an owned type such as `EndianRcSlice`.
     let dwarf = dwarf_cow.borrow(&borrow_section);
 
     // Iterate over the compilation units.

crates/examples/src/bin/simple_line.rs

@@ -29,7 +29,7 @@ fn dump_file(object: &object::File, endian: gimli::RunTimeEndian) -> Result<(),
     };
 
     // Load all of the sections.
-    let dwarf_cow = gimli::Dwarf::load(&load_section)?;
+    let dwarf_cow = gimli::DwarfSections::load(&load_section)?;
 
     // Borrow a `Cow<[u8]>` to create an `EndianSlice`.
     let borrow_section: &dyn for<'a> Fn(

src/read/abbrev.rs

@@ -66,17 +66,7 @@ impl<T> DebugAbbrev<T> {
     ///
     /// This is useful when `R` implements `Reader` but `T` does not.
     ///
-    /// ## Example Usage
-    ///
-    /// ```rust,no_run
-    /// # let load_section = || unimplemented!();
-    /// // Read the DWARF section into a `Vec` with whatever object loader you're using.
-    /// let owned_section: gimli::DebugAbbrev<Vec<u8>> = load_section();
-    /// // Create a reference to the DWARF section.
-    /// let section = owned_section.borrow(|section| {
-    ///     gimli::EndianSlice::new(&section, gimli::LittleEndian)
-    /// });
-    /// ```
+    /// Used by `DwarfSections::borrow`.
     pub fn borrow<'a, F, R>(&'a self, mut borrow: F) -> DebugAbbrev<R>
     where
         F: FnMut(&'a T) -> R,

src/read/addr.rs

@@ -45,17 +45,7 @@ impl<T> DebugAddr<T> {
     ///
     /// This is useful when `R` implements `Reader` but `T` does not.
     ///
-    /// ## Example Usage
-    ///
-    /// ```rust,no_run
-    /// # let load_section = || unimplemented!();
-    /// // Read the DWARF section into a `Vec` with whatever object loader you're using.
-    /// let owned_section: gimli::DebugAddr<Vec<u8>> = load_section();
-    /// // Create a reference to the DWARF section.
-    /// let section = owned_section.borrow(|section| {
-    ///     gimli::EndianSlice::new(&section, gimli::LittleEndian)
-    /// });
-    /// ```
+    /// Used by `DwarfSections::borrow`.
     pub fn borrow<'a, F, R>(&'a self, mut borrow: F) -> DebugAddr<R>
     where
         F: FnMut(&'a T) -> R,

src/read/aranges.rs

@@ -59,17 +59,7 @@ impl<T> DebugAranges<T> {
     ///
     /// This is useful when `R` implements `Reader` but `T` does not.
     ///
-    /// ## Example Usage
-    ///
-    /// ```rust,no_run
-    /// # let load_section = || unimplemented!();
-    /// // Read the DWARF section into a `Vec` with whatever object loader you're using.
-    /// let owned_section: gimli::DebugAranges<Vec<u8>> = load_section();
-    /// // Create a reference to the DWARF section.
-    /// let section = owned_section.borrow(|section| {
-    ///     gimli::EndianSlice::new(&section, gimli::LittleEndian)
-    /// });
-    /// ```
+    /// Used by `DwarfSections::borrow`.
     pub fn borrow<'a, F, R>(&'a self, mut borrow: F) -> DebugAranges<R>
     where
         F: FnMut(&'a T) -> R,