From 504729a4a0c8f3e0d8fc9159e0273150b169e184 Mon Sep 17 00:00:00 2001
From: Titus Wormer <tituswormer@gmail.com>
Date: Fri, 12 Aug 2022 14:21:53 +0200
Subject: Refactor to improve docs of each function

---
 src/util/edit_map.rs |  3 +--
 src/util/skip.rs     | 15 +++++++++------
 src/util/slice.rs    | 20 ++++++++------------
 3 files changed, 18 insertions(+), 20 deletions(-)

(limited to 'src/util')

diff --git a/src/util/edit_map.rs b/src/util/edit_map.rs
index 59adfca..11ac486 100644
--- a/src/util/edit_map.rs
+++ b/src/util/edit_map.rs
@@ -53,8 +53,7 @@ fn shift_links(events: &mut [Event], jumps: &[(usize, usize, usize)]) {
     }
 }
 
-/// Make it easy to insert and remove things while being performant and keeping
-/// links in check.
+/// Tracks a bunch of edits.
 #[derive(Debug)]
 pub struct EditMap {
     /// Record of changes.
diff --git a/src/util/skip.rs b/src/util/skip.rs
index 371418f..46cbb4a 100644
--- a/src/util/skip.rs
+++ b/src/util/skip.rs
@@ -12,15 +12,18 @@ pub fn opt_back(events: &[Event], index: usize, names: &[Name]) -> usize {
     skip_opt_impl(events, index, names, false)
 }
 
-pub fn to_back(events: &[Event], index: usize, names: &[Name]) -> usize {
-    to_impl(events, index, names, false)
-}
-
+/// Skip from `index` forwards to `names`.
 pub fn to(events: &[Event], index: usize, names: &[Name]) -> usize {
     to_impl(events, index, names, true)
 }
 
-pub fn to_impl(events: &[Event], mut index: usize, names: &[Name], forward: bool) -> usize {
+/// Skip from `index` backwards to `names`.
+pub fn to_back(events: &[Event], index: usize, names: &[Name]) -> usize {
+    to_impl(events, index, names, false)
+}
+
+/// Skip to something.
+fn to_impl(events: &[Event], mut index: usize, names: &[Name], forward: bool) -> usize {
     while index < events.len() {
         let current = &events[index].name;
 
@@ -34,7 +37,7 @@ pub fn to_impl(events: &[Event], mut index: usize, names: &[Name], forward: bool
     index
 }
 
-/// Skip internals.
+/// Skip past things.
 fn skip_opt_impl(events: &[Event], mut index: usize, names: &[Name], forward: bool) -> usize {
     let mut balance = 0;
     let open = if forward { Kind::Enter } else { Kind::Exit };
diff --git a/src/util/slice.rs b/src/util/slice.rs
index 34adf32..e70078a 100644
--- a/src/util/slice.rs
+++ b/src/util/slice.rs
@@ -4,7 +4,7 @@ use crate::constant::TAB_SIZE;
 use crate::event::{Event, Kind, Point};
 use std::str;
 
-/// A range between two places.
+/// A range between two points.
 #[derive(Debug)]
 pub struct Position<'a> {
     pub start: &'a Point,
@@ -53,9 +53,9 @@ impl<'a> Position<'a> {
     }
 }
 
-/// Chars belonging to a range.
+/// Bytes belonging to a range.
 ///
-/// Includes information on virtual spaces before and after the chars.
+/// Includes information on virtual spaces before and after the bytes.
 #[derive(Debug)]
 pub struct Slice<'a> {
     pub bytes: &'a [u8],
@@ -64,7 +64,7 @@ pub struct Slice<'a> {
 }
 
 impl<'a> Slice<'a> {
-    /// Get the slice belonging to a point.
+    /// Get a slice for a single point.
     pub fn from_point(bytes: &'a [u8], point: &Point) -> Slice<'a> {
         let mut before = point.vs;
         let mut start = point.index;
@@ -88,16 +88,14 @@ impl<'a> Slice<'a> {
         }
     }
 
-    /// Create a slice from one index.
-    ///
-    /// Indices are places in `bytes`.
+    /// Get a slice for a single index.
     ///
     /// > 👉 **Note**: indices cannot represent virtual spaces.
     pub fn from_index(bytes: &'a [u8], index: usize) -> Slice<'a> {
         Slice::from_indices(bytes, index, index + 1)
     }
 
-    /// Get the slice belonging to a position.
+    /// Get a slice for a position.
     pub fn from_position(bytes: &'a [u8], position: &Position) -> Slice<'a> {
         let mut before = position.start.vs;
         let mut after = position.end.vs;
@@ -125,9 +123,7 @@ impl<'a> Slice<'a> {
         }
     }
 
-    /// Create a slice from two indices.
-    ///
-    /// Indices are places in `bytes`.
+    /// Get a slice for two indices.
     ///
     /// > 👉 **Note**: indices cannot represent virtual spaces.
     pub fn from_indices(bytes: &'a [u8], start: usize, end: usize) -> Slice<'a> {
@@ -157,7 +153,7 @@ impl<'a> Slice<'a> {
 
     /// Turn the slice into a `&str`.
     ///
-    /// Does not support virtual spaces.
+    /// > 👉 **Note**: cannot represent virtual spaces.
     pub fn as_str(&self) -> &str {
         str::from_utf8(self.bytes).unwrap()
     }
-- 
cgit