Start documenting display_map module

Piotr Osiewicz created 2 years ago

Change summary

crates/editor/src/display_map.rs          | 37 ++++++++++++------------
crates/editor/src/display_map/fold_map.rs | 10 +++---
2 files changed, 24 insertions(+), 23 deletions(-)

Detailed changes

crates/editor/src/display_map.rs

@@ -1,3 +1,22 @@
+//! This module defines where the text should be displayed in an [`Editor`][Editor].
+//!
+//! Not literally though - rendering, layout and all that jazz is a responsibility of [`EditorElement`][EditorElement].
+//! Instead, [`DisplayMap`] decides where Inlays/Inlay hints are displayed, when
+//! to apply a soft wrap, where to add fold indicators, whether there are any tabs in the buffer that
+//! we display as spaces and where to display custom blocks (like diagnostics).
+//! Seems like a lot? That's because it is. [`DisplayMap`] is conceptually made up
+//! of several smaller structures that form a hierarchy (starting at the bottom):
+//! - [`InlayMap`] that decides where the [`Inlay`]s should be displayed.
+//! - [`FoldMap`] that decides where the fold indicators should be; it also tracks parts of a source file that are currently folded.
+//! - [`TabMap`] that keeps track of hard tabs in a buffer.
+//! - [`WrapMap`] that handles soft wrapping.
+//! - [`BlockMap`] that tracks custom blocks such as diagnostics that should be displayed within buffer.
+//! - [`DisplayMap`] that adds background highlights to the regions of text.
+//! Each one of those builds on top of preceding map.
+//!
+//! [Editor]: crate::Editor
+//! [EditorElement]: crate::element::EditorElement
+
 mod block_map;
 mod fold_map;
 mod inlay_map;
@@ -971,24 +990,6 @@ impl ToDisplayPoint for Anchor {
     }
 }
 
-pub fn next_rows(display_row: u32, display_map: &DisplaySnapshot) -> impl Iterator<Item = u32> {
-    let max_row = display_map.max_point().row();
-    let start_row = display_row + 1;
-    let mut current = None;
-    std::iter::from_fn(move || {
-        if current == None {
-            current = Some(start_row);
-        } else {
-            current = Some(current.unwrap() + 1)
-        }
-        if current.unwrap() > max_row {
-            None
-        } else {
-            current
-        }
-    })
-}
-
 #[cfg(test)]
 pub mod tests {
     use super::*;

crates/editor/src/display_map/fold_map.rs

@@ -71,10 +71,10 @@ impl<'a> sum_tree::Dimension<'a, TransformSummary> for FoldPoint {
     }
 }
 
-pub struct FoldMapWriter<'a>(&'a mut FoldMap);
+pub(crate) struct FoldMapWriter<'a>(&'a mut FoldMap);
 
 impl<'a> FoldMapWriter<'a> {
-    pub fn fold<T: ToOffset>(
+    pub(crate) fn fold<T: ToOffset>(
         &mut self,
         ranges: impl IntoIterator<Item = Range<T>>,
     ) -> (FoldSnapshot, Vec<FoldEdit>) {
@@ -129,7 +129,7 @@ impl<'a> FoldMapWriter<'a> {
         (self.0.snapshot.clone(), edits)
     }
 
-    pub fn unfold<T: ToOffset>(
+    pub(crate) fn unfold<T: ToOffset>(
         &mut self,
         ranges: impl IntoIterator<Item = Range<T>>,
         inclusive: bool,
@@ -178,14 +178,14 @@ impl<'a> FoldMapWriter<'a> {
     }
 }
 
-pub struct FoldMap {
+pub(crate) struct FoldMap {
     snapshot: FoldSnapshot,
     ellipses_color: Option<Hsla>,
     next_fold_id: FoldId,
 }
 
 impl FoldMap {
-    pub fn new(inlay_snapshot: InlaySnapshot) -> (Self, FoldSnapshot) {
+    pub(crate) fn new(inlay_snapshot: InlaySnapshot) -> (Self, FoldSnapshot) {
         let this = Self {
             snapshot: FoldSnapshot {
                 folds: Default::default(),