Add documentation to many core editor types (#7919)

Hopefully this makes it a bit easier for new contributors to dive into
the codebase :)

Release Notes:

- Improved documentation for many core editor types

---------

Co-authored-by: Nathan Sobo <nathan@zed.dev>

crates/editor/src/display_map.rs

@@ -67,15 +67,27 @@ pub trait ToDisplayPoint {
 type TextHighlights = TreeMap<Option<TypeId>, Arc<(HighlightStyle, Vec<Range<Anchor>>)>>;
 type InlayHighlights = BTreeMap<TypeId, HashMap<InlayId, (HighlightStyle, InlayHighlight)>>;
 
+/// Decides how text in a [`MultiBuffer`] should be displayed in a buffer, handling inlay hints,
+/// folding, hard tabs, soft wrapping, custom blocks (like diagnostics), and highlighting.
+///
+/// See the [module level documentation](self) for more information.
 pub struct DisplayMap {
+    /// The buffer that we are displaying.
     buffer: Model<MultiBuffer>,
     buffer_subscription: BufferSubscription,
-    fold_map: FoldMap,
+    /// Decides where the [`Inlay`]s should be displayed.
     inlay_map: InlayMap,
+    /// Decides where the fold indicators should be and tracks parts of a source file that are currently folded.
+    fold_map: FoldMap,
+    /// Keeps track of hard tabs in a buffer.
     tab_map: TabMap,
+    /// Handles soft wrapping.
     wrap_map: Model<WrapMap>,
+    /// Tracks custom blocks such as diagnostics that should be displayed within buffer.
     block_map: BlockMap,
+    /// Regions of text that should be highlighted.
     text_highlights: TextHighlights,
+    /// Regions of inlays that should be highlighted.
     inlay_highlights: InlayHighlights,
     pub clip_at_line_ends: bool,
 }

crates/editor/src/display_map/block_map.rs

@@ -22,6 +22,9 @@ use text::Edit;
 
 const NEWLINES: &[u8] = &[b'\n'; u8::MAX as usize];
 
+/// Tracks custom blocks such as diagnostics that should be displayed within buffer.
+///
+/// See the [`display_map` module documentation](crate::display_map) for more information.
 pub struct BlockMap {
     next_block_id: AtomicUsize,
     wrap_snapshot: RefCell<WrapSnapshot>,

crates/editor/src/display_map/fold_map.rs

@@ -178,6 +178,9 @@ impl<'a> FoldMapWriter<'a> {
     }
 }
 
+/// Decides where the fold indicators should be; also tracks parts of a source file that are currently folded.
+///
+/// See the [`display_map` module documentation](crate::display_map) for more information.
 pub(crate) struct FoldMap {
     snapshot: FoldSnapshot,
     ellipses_color: Option<Hsla>,

crates/editor/src/display_map/inlay_map.rs

@@ -16,6 +16,9 @@ use text::{Patch, Rope};
 
 use super::Highlights;
 
+/// Decides where the [`Inlay`]s should be displayed.
+///
+/// See the [`display_map` module documentation](crate::display_map) for more information.
 pub struct InlayMap {
     snapshot: InlaySnapshot,
     inlays: Vec<Inlay>,

crates/editor/src/display_map/tab_map.rs

@@ -9,6 +9,9 @@ use sum_tree::Bias;
 
 const MAX_EXPANSION_COLUMN: u32 = 256;
 
+/// Keeps track of hard tabs in a text buffer.
+///
+/// See the [`display_map` module documentation](crate::display_map) for more information.
 pub struct TabMap(TabSnapshot);
 
 impl TabMap {

crates/editor/src/display_map/wrap_map.rs

@@ -15,6 +15,9 @@ use text::Patch;
 pub use super::tab_map::TextSummary;
 pub type WrapEdit = text::Edit<u32>;
 
+/// Handles soft wrapping of text.
+///
+/// See the [`display_map` module documentation](crate::display_map) for more information.
 pub struct WrapMap {
     snapshot: WrapSnapshot,
     pending_edits: VecDeque<(TabSnapshot, Vec<TabEdit>)>,

crates/editor/src/editor.rs

@@ -290,7 +290,7 @@ pub enum SelectPhase {
 }
 
 #[derive(Clone, Debug)]
-pub(crate) enum SelectMode {
+pub enum SelectMode {
     Character,
     Word(Range<Anchor>),
     Line(Range<Anchor>),
@@ -349,10 +349,16 @@ type CompletionId = usize;
 type BackgroundHighlight = (fn(&ThemeColors) -> Hsla, Vec<Range<Anchor>>);
 type InlayBackgroundHighlight = (fn(&ThemeColors) -> Hsla, Vec<InlayHighlight>);
 
+/// Zed's primary text input `View`, allowing users to edit a [`MultiBuffer`]
+///
+/// See the [module level documentation](self) for more information.
 pub struct Editor {
     handle: WeakView<Self>,
     focus_handle: FocusHandle,
+    /// The text buffer being edited
     buffer: Model<MultiBuffer>,
+    /// Map of how text in the buffer should be displayed.
+    /// Handles soft wraps, folds, fake inlay text insertions, etc.
     display_map: Model<DisplayMap>,
     pub selections: SelectionsCollection,
     pub scroll_manager: ScrollManager,

crates/editor/src/selections_collection.rs

@@ -29,8 +29,11 @@ pub struct SelectionsCollection {
     buffer: Model<MultiBuffer>,
     pub next_selection_id: usize,
     pub line_mode: bool,
-    disjoint: Arc<[Selection<Anchor>]>,
-    pending: Option<PendingSelection>,
+    /// The non-pending, non-overlapping selections.
+    /// The [SelectionsCollection::pending] selection could possibly overlap these
+    pub disjoint: Arc<[Selection<Anchor>]>,
+    /// A pending selection, such as when the mouse is being dragged
+    pub pending: Option<PendingSelection>,
 }
 
 impl SelectionsCollection {