Clean up documentation

The first paragraph of the documentation ends up as a summary line on
rustdoc; having it be a single short sentence integrates well with this
behaviour.

Author: nagisa

thorin/src/error.rs

@@ -19,31 +19,37 @@ impl<'a, T: StdError + 'a> AsDynError<'a> for T {
 #[derive(Debug)]
 #[non_exhaustive]
 pub enum Error {
-    /// Failure to read input file, this error occurs in the `Session::read_input` function
-    /// provided by the user of `thorin`.
+    /// Failure to read input file.
+    ///
+    /// This error occurs in the `Session::read_input` function provided by the user of `thorin`.
     ReadInput(std::io::Error),
-    /// Failed to parse kind of input file. Input file kind is necessary to determine how to parse
-    /// the rest of the input, and to validate that the input file is of a type that `thorin` can
-    /// process.
+    /// Failed to parse kind of input file.
+    ///
+    /// Input file kind is necessary to determine how to parse the rest of the input, and to
+    /// validate that the input file is of a type that `thorin` can process.
     ParseFileKind(object::Error),
     /// Failed to parse object file.
     ParseObjectFile(object::Error),
     /// Failed to parse archive file.
     ParseArchiveFile(object::Error),
     /// Failed to parse archive member.
     ParseArchiveMember(object::Error),
-    /// Invalid kind of input. Only archive and elf files are supported input files.
+    /// Invalid kind of input.
+    ///
+    /// Only archive and elf files are supported input files.
     InvalidInputKind,
-    /// Failed to decompress data. `thorin` uses `object` for decompression, so `object` probably
-    /// didn't have support for the type of compression used.
+    /// Failed to decompress data.
+    ///
+    /// `thorin` uses `object` for decompression, so `object` probably didn't have support for the
+    /// type of compression used.
     DecompressData(object::Error),
     /// Section without a name.
     NamelessSection(object::Error, usize),
     /// Relocation has invalid symbol for a section.
     RelocationWithInvalidSymbol(String, usize),
     /// Multiple relocations for a section.
     MultipleRelocations(String, usize),
-    /// Unsupport relocations for a section.
+    /// Unsupported relocations for a section.
     UnsupportedRelocation(String, usize),
     /// Input object that has a `DwoId` (or `DebugTypeSignature`) does not have a
     /// `DW_AT_GNU_dwo_name` or `DW_AT_dwo_name` attribute.
@@ -72,8 +78,10 @@ pub enum Error {
     OffsetAtIndex(gimli::read::Error, u64),
     /// Failed to read string from `.debug_str` at offset.
     StrAtOffset(gimli::read::Error, usize),
-    /// Failed to parse index section. If an input file is a DWARF package, its index section needs
-    /// to be read to ensure that the contributions within it are preserved.
+    /// Failed to parse index section.
+    ///
+    /// If an input file is a DWARF package, its index section needs to be read to ensure that the
+    /// contributions within it are preserved.
     ParseIndex(gimli::read::Error, String),
     /// Compilation unit in DWARF package is not its index.
     UnitNotInIndex(u64),

thorin/src/ext.rs

@@ -22,6 +22,8 @@ pub(crate) trait CompressedDataRangeExt<'input, 'session: 'input>:
     ObjectSection<'input>
 {
     /// Return the decompressed contents of the section data in the given range.
+    ///
+    /// Decompression happens only if the data is compressed.
     fn compressed_data_range(
         &self,
         sess: &'session impl Session<RelocationMap>,
@@ -96,7 +98,9 @@ impl<'input, Endian: gimli::Endianity> IndexSectionExt<'input, Endian, EndianSli
 pub(crate) trait PackageFormatExt {
     /// Returns `true` if this `Encoding` would produce to a DWARF 5-standardized package file.
     ///
-    /// See Sec 7.3.5 and Appendix F of [DWARF specification](https://dwarfstd.org/doc/DWARF5.pdf).
+    /// See Sec 7.3.5 and Appendix F of the [DWARF specification].
+    ///
+    /// [DWARF specification]: https://dwarfstd.org/doc/DWARF5.pdf
     fn is_std_dwarf_package_format(&self) -> bool;
 
     /// Returns `true` if this `Encoding` would produce a GNU Extension DWARF package file

thorin/src/package.rs

@@ -424,8 +424,10 @@ impl<'file> InProgressDwarfPackage<'file> {
         &self.contained_units
     }
 
-    /// Process an input DWARF object. Copies relevant sections, compilation/type units and strings
-    /// from DWARF object into output object.
+    /// Process an input DWARF object.
+    ///
+    /// Copies relevant debug sections, compilation/type units and strings from the `input` DWARF
+    /// object into this DWARF package.
     #[tracing::instrument(level = "trace", skip(sess, input,))]
     pub(crate) fn add_input_object<'input, 'session: 'input>(
         &mut self,