docs: Clarify reference end position documentation (#491)

* docs: Clarify reference end position documentation

* refactor: Add explicit lifetimes to iterator return types

* refactor: Use is_multiple_of for clarity

Author: fxwiegand

src/bam/buffer.rs

@@ -157,12 +157,12 @@ impl RecordBuffer {
     }
 
     /// Iterate over records that have been fetched with `fetch`.
-    pub fn iter(&self) -> vec_deque::Iter<Rc<bam::Record>> {
+    pub fn iter(&self) -> vec_deque::Iter<'_, Rc<bam::Record>> {
         self.inner.iter()
     }
 
     /// Iterate over mutable references to records that have been fetched with `fetch`.
-    pub fn iter_mut(&mut self) -> vec_deque::IterMut<Rc<bam::Record>> {
+    pub fn iter_mut(&mut self) -> vec_deque::IterMut<'_, Rc<bam::Record>> {
         self.inner.iter_mut()
     }
 

src/bam/ext.rs

@@ -301,7 +301,7 @@ pub trait BamRecordExtensions {
     /// left most aligned reference position of the read on the reference genome.
     fn reference_start(&self) -> i64;
 
-    /// right most aligned reference position of the read on the reference genome.
+    /// right most aligned absolute reference position of the read on the reference genome.
     fn reference_end(&self) -> i64;
 
     /// infer the query length from the cigar string, optionally include hard clipped bases
@@ -435,7 +435,7 @@ impl BamRecordExtensions for bam::Record {
         self.pos()
     }
 
-    /// Calculate the rightmost base position of an alignment on the reference genome.
+    /// Calculate the rightmost absolute reference base position of an alignment on the reference genome.
     /// Returns the coordinate of the first base after the alignment (0-based).
     fn reference_end(&self) -> i64 {
         unsafe { htslib::bam_endpos(self.inner_ptr()) }

src/bam/header.rs

@@ -106,7 +106,7 @@ impl Header {
     }
 
     /// Returns an iterator of comment lines.
-    pub fn comments(&self) -> impl Iterator<Item = Cow<str>> {
+    pub fn comments(&self) -> impl Iterator<Item = Cow<'_, str>> {
         self.records.iter().flat_map(|r| {
             r.split(|x| x == &b'\n')
                 .filter(|x| x.starts_with(b"@CO\t"))

src/bam/record.rs

@@ -103,7 +103,7 @@ impl Default for Record {
 #[inline]
 fn extranul_from_qname(qname: &[u8]) -> usize {
     let qlen = qname.len() + 1;
-    if qlen % 4 != 0 {
+    if !qlen.is_multiple_of(4) {
         4 - qlen % 4
     } else {
         0
@@ -833,7 +833,7 @@ impl Record {
     ///
     /// When an error occurs, the `Err` variant will be returned
     /// and the iterator will not be able to advance anymore.
-    pub fn aux_iter(&self) -> AuxIter {
+    pub fn aux_iter(&self) -> AuxIter<'_> {
         AuxIter {
             // In order to get to the aux data section of a `bam::Record`
             // we need to skip fields in front of it
@@ -1272,14 +1272,14 @@ impl Record {
     ///    }
     ///    assert_eq!(mod_count, 14);
     /// ```
-    pub fn basemods_iter(&self) -> Result<BaseModificationsIter> {
+    pub fn basemods_iter(&self) -> Result<BaseModificationsIter<'_>> {
         BaseModificationsIter::new(self)
     }
 
     /// An iterator that returns all of the modifications for each position as a vector.
     /// This is useful for the case where multiple possible modifications can be annotated
     /// at a single position (for example a C could be 5-mC or 5-hmC)
-    pub fn basemods_position_iter(&self) -> Result<BaseModificationsPositionIter> {
+    pub fn basemods_position_iter(&self) -> Result<BaseModificationsPositionIter<'_>> {
         BaseModificationsPositionIter::new(self)
     }
 
@@ -1658,7 +1658,7 @@ where
     }
 
     /// Returns an iterator over the array.
-    pub fn iter(&self) -> AuxArrayIter<T> {
+    pub fn iter(&self) -> AuxArrayIter<'_, T> {
         AuxArrayIter {
             index: 0,
             array: self,