Refactor to clean and document `edit_map`

2 files changed, 20 insertions, 4 deletions

diff --git a/readme.md b/readme.md
index 765c40a..e750b98 100644
--- a/readme.md
+++ b/readme.md
@@ -122,14 +122,12 @@ cargo doc --document-private-items
 
 #### Docs
 
-- [ ] (1) `edit_map`
 - [ ] (1) Go through all bnf
 - [ ] (1) Go through all docs
 - [ ] (1) Add overview docs on how everything works
 
 #### Refactor
 
-- [ ] (1) Clean shifting, assertions in `edit_map`
 - [ ] (1) Use `link_to` in more places? It’s probably better
 - [ ] (1) Use `edit_map` in `subtokenize`
 
@@ -276,3 +274,4 @@ important.
 - [x] (3) Clean compiler
 - [x] (1) Parse initial and final space_or_tab of paragraphs (in string, text)
 - [x] (1) Refactor to clean and document `space_or_tab`
+- [x] (1) Refactor to clean and document `edit_map`
diff --git a/src/util/edit_map.rs b/src/util/edit_map.rs
index db9c887..0d58f01 100644
--- a/src/util/edit_map.rs
+++ b/src/util/edit_map.rs
@@ -1,9 +1,22 @@
-use crate::tokenizer::Event;
+//! Helpers to deal with several changes in events, batching them together.
+//!
+//! Preferably, changes should be kept to a minumum.
+//! Sometimes, it’s needed to change the list of events, because parsing can be
+//! messy, and it helps to expose a cleaner interface of events to the compiler
+//! and other users.
+//! It can also help to merge many adjacent similar events.
+//! And, in other cases, it’s needed to parse subcontent: pass some events
+//! through another tokenizer and inject the result.
 
 /// To do: could we do without `HashMap`, so we don’t need `std`?
 use std::collections::HashMap;
 
-pub fn shift_links(events: &mut [Event], jumps: &[(usize, isize)]) {
+use crate::tokenizer::Event;
+
+/// Shift `previous` and `next` links according to `jumps`.
+///
+/// This fixes links in case there are events removed or added between them.
+fn shift_links(events: &mut [Event], jumps: &[(usize, isize)]) {
     let map = |before| {
         let mut jump_index = 0;
         let mut jump = 0;
@@ -38,7 +51,9 @@ pub fn shift_links(events: &mut [Event], jumps: &[(usize, isize)]) {
 /// Make it easy to insert and remove things while being performant and keeping
 /// links in check.
 pub struct EditMap {
+    /// Whether this map was consumed already.
     consumed: bool,
+    /// Record of changes.
     map: HashMap<usize, (usize, Vec<Event>)>,
 }
 
@@ -55,6 +70,8 @@ impl EditMap {
         assert!(!self.consumed, "cannot add after consuming");
 
         if let Some((curr_remove, mut curr_add)) = self.map.remove(&index) {
+            // To do: these might have to be split in several chunks instead
+            // of one, if links in `curr_add` are supported.
             remove += curr_remove;
             curr_add.append(&mut add);
             add = curr_add;