From 96c3ca8687ce077b7758177594d747dfcfa654f4 Mon Sep 17 00:00:00 2001
From: est31 <MTest31@outlook.com>
Date: Mon, 28 Oct 2019 15:46:00 +0100
Subject: [PATCH] Document the builder functions

---
 src/de.rs | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/src/de.rs b/src/de.rs
index 5e54e611..190a8e03 100644
--- a/src/de.rs
+++ b/src/de.rs
@@ -323,6 +323,16 @@ impl<'de, 'b> de::Deserializer<'de> for &'b mut Deserializer<'de> {
     }
 }
 
+// Builds a datastructure that allows for efficient sublinear lookups.
+// The returned HashMap contains a mapping from table header to
+// list of tables table with that precise name, the tables being identified
+// by their index in the passed slice. We use a list as the implementation
+// uses this datastructure for arrays as well as tables,
+// so if any top level [[name]] array contains multiple entries,
+// there are multiple entires in the list.
+// The lookup is performed in the `SeqAccess` implementation of `MapVisitor`.
+// The lists are ordered, which we exploit in the search code by using
+// bisection.
 fn build_table_indices<'de>(tables: &[Table<'de>]) -> HashMap<Vec<Cow<'de, str>>, Vec<usize>> {
     let mut res = HashMap::new();
     for (i, table) in tables.iter().enumerate() {
@@ -332,6 +342,20 @@ fn build_table_indices<'de>(tables: &[Table<'de>]) -> HashMap<Vec<Cow<'de, str>>
     res
 }
 
+// Builds a datastructure that allows for efficient sublinear lookups.
+// The returned HashMap contains a mapping from table header to
+// list of tables table whose name at least starts with the specified
+// name, the tables being identified by their index in the passed slice.
+//
+// A list is used for two reasons: First, the implementation also
+// stores arrays in the same datastructure and any top level array
+// of size 2 or greater creates multiple entries in the list with the
+// same shared name. Second, there can be multiple tables sharing
+// the same prefix.
+//
+// The lookup is performed in the `MapAccess` implementation of `MapVisitor`.
+// The lists are ordered, which we exploit in the search code by using
+// bisection.
 fn build_table_pindices<'de>(tables: &[Table<'de>]) -> HashMap<Vec<Cow<'de, str>>, Vec<usize>> {
     let mut res = HashMap::new();
     for (i, table) in tables.iter().enumerate() {