Document main workspace structs (#9772)

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>,

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>>,

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,

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>>,