From e3894a4e1e1e8e503a8c414bc386c2e9d73b29cb Mon Sep 17 00:00:00 2001
From: Kirill Bulatov <kirill@zed.dev>
Date: Mon, 25 Mar 2024 16:09:51 +0100
Subject: [PATCH] Document main workspace structs (#9772)

---
 crates/project/src/project.rs      |  5 +++++
 crates/workspace/src/dock.rs       |  2 ++
 crates/workspace/src/pane.rs       |  4 ++++
 crates/workspace/src/pane_group.rs |  3 +++
 crates/workspace/src/workspace.rs  |  6 ++++++
 crates/worktree/src/worktree.rs    | 11 +++++++++++
 6 files changed, 31 insertions(+)

diff --git a/crates/project/src/project.rs b/crates/project/src/project.rs
index 01d416fce6..ecd0c54da8 100644
--- a/crates/project/src/project.rs
+++ b/crates/project/src/project.rs
@@ -141,6 +141,11 @@ pub enum OpenedBufferEvent {
     Err(BufferId, Arc<anyhow::Error>),
 }
 
+/// Semantics-aware entity that is relevant to one or more [`Worktree`] with the files.
+/// `Project` is responsible for tasks, LSP and collab queries, synchronizing worktree states accordingly.
+/// Maps [`Worktree`] entries with its own logic using [`ProjectEntryId`] and [`ProjectPath`] structs.
+///
+/// Can be either local (for the project opened on the same host) or remote.(for collab projects, browsed by multiple remote users).
 pub struct Project {
     worktrees: Vec<WorktreeHandle>,
     active_entry: Option<ProjectEntryId>,
diff --git a/crates/workspace/src/dock.rs b/crates/workspace/src/dock.rs
index ee79179dc8..075d69d781 100644
--- a/crates/workspace/src/dock.rs
+++ b/crates/workspace/src/dock.rs
@@ -140,6 +140,8 @@ impl From<&dyn PanelHandle> for AnyView {
     }
 }
 
+/// A container with a fixed [`DockPosition`] adjacent to a certain widown edge.
+/// Can contain multiple panels and show/hide itself with all contents.
 pub struct Dock {
     position: DockPosition,
     panel_entries: Vec<PanelEntry>,
diff --git a/crates/workspace/src/pane.rs b/crates/workspace/src/pane.rs
index ff6063b4e8..41ba2079f9 100644
--- a/crates/workspace/src/pane.rs
+++ b/crates/workspace/src/pane.rs
@@ -159,6 +159,10 @@ impl fmt::Debug for Event {
     }
 }
 
+/// A container for 0 to many items that are open in the workspace.
+/// Treats all items uniformly via the [`ItemHandle`] trait, whether it's an editor, search results multibuffer, terminal or something else,
+/// responsible for managing item tabs, focus and zoom states and drag and drop features.
+/// Can be split, see `PaneGroup` for more details.
 pub struct Pane {
     focus_handle: FocusHandle,
     items: Vec<Box<dyn ItemHandle>>,
diff --git a/crates/workspace/src/pane_group.rs b/crates/workspace/src/pane_group.rs
index 1dc07a0536..b7f0824c9c 100644
--- a/crates/workspace/src/pane_group.rs
+++ b/crates/workspace/src/pane_group.rs
@@ -16,6 +16,9 @@ pub const HANDLE_HITBOX_SIZE: f32 = 4.0;
 const HORIZONTAL_MIN_SIZE: f32 = 80.;
 const VERTICAL_MIN_SIZE: f32 = 100.;
 
+/// One or many panes, arranged in a horizontal or vertical axis due to a split.
+/// Panes have all their tabs and capabilities preserved, and can be split again or resized.
+/// Single-pane group is a regular pane.
 #[derive(Clone)]
 pub struct PaneGroup {
     pub(crate) root: Member,
diff --git a/crates/workspace/src/workspace.rs b/crates/workspace/src/workspace.rs
index c8d2c021b8..d55c3348c0 100644
--- a/crates/workspace/src/workspace.rs
+++ b/crates/workspace/src/workspace.rs
@@ -529,6 +529,12 @@ pub enum OpenVisible {
     OnlyDirectories,
 }
 
+/// Collects everything project-related for a certain window opened.
+/// In some way, is a counterpart of a window, as the [`WindowHandle`] could be downcast into `Workspace`.
+///
+/// A `Workspace` usually consists of 1 or more projects, a central pane group, 3 docks and a status bar.
+/// The `Workspace` owns everybody's state and serves as a default, "global context",
+/// that can be used to register a global action to be triggered from any place in the window.
 pub struct Workspace {
     weak_self: WeakView<Self>,
     workspace_actions: Vec<Box<dyn Fn(Div, &mut ViewContext<Self>) -> Div>>,
diff --git a/crates/worktree/src/worktree.rs b/crates/worktree/src/worktree.rs
index 2ad7436096..2751797842 100644
--- a/crates/worktree/src/worktree.rs
+++ b/crates/worktree/src/worktree.rs
@@ -82,6 +82,17 @@ pub const FS_WATCH_LATENCY: Duration = Duration::from_millis(100);
 #[derive(Copy, Clone, PartialEq, Eq, Debug, Hash, PartialOrd, Ord)]
 pub struct WorktreeId(usize);
 
+/// A set of local or remote files that are being opened as part of a project.
+/// Responsible for tracking related FS (for local)/collab (for remote) events and corresponding updates.
+/// Stores git repositories data and the diagnostics for the file(s).
+///
+/// Has an absolute path, and may be set to be visible in Zed UI or not.
+/// May correspond to a directory or a single file.
+/// Possible examples:
+/// * a drag and dropped file — may be added as an invisible, "ephemeral" entry to the current worktree
+/// * a directory opened in Zed — may be added as a visible entry to the current worktree
+///
+/// Uses [`Entry`] to track the state of each file/directory, can look up absolute paths for entries.
 pub enum Worktree {
     Local(LocalWorktree),
     Remote(RemoteWorktree),