Write documentation for `pane_grid`

1 files changed, 102 insertions, 2 deletions

diff --git a/native/src/widget/pane_grid/state.rs b/native/src/widget/pane_grid/state.rs
index 9103dcd0..6c80cacc 100644
--- a/native/src/widget/pane_grid/state.rs
+++ b/native/src/widget/pane_grid/state.rs
@@ -6,6 +6,20 @@ use crate::{
 
 use std::collections::HashMap;
 
+/// The state of a [`PaneGrid`].
+///
+/// It keeps track of the state of each [`Pane`] and the position of each
+/// [`Split`].
+///
+/// The [`State`] needs to own any mutable contents a [`Pane`] may need. This is
+/// why this struct is generic over the type `T`. Values of this type are
+/// provided to the view function of [`PaneGrid::new`] for displaying each
+/// [`Pane`].
+///
+/// [`PaneGrid`]: struct.PaneGrid.html
+/// [`PaneGrid::new`]: struct.PaneGrid.html#method.new
+/// [`State`]: struct.State.html
+/// [`Pane`]: struct.Pane.html
 #[derive(Debug)]
 pub struct State<T> {
     pub(super) panes: HashMap<Pane, T>,
@@ -13,13 +27,28 @@ pub struct State<T> {
     pub(super) modifiers: keyboard::ModifiersState,
 }
 
+/// The current focus of a [`Pane`].
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum Focus {
+    /// The [`Pane`] is just focused.
+    ///
+    /// [`Pane`]: struct.Pane.html
     Idle,
+
+    /// The [`Pane`] is being dragged.
+    ///
+    /// [`Pane`]: struct.Pane.html
     Dragging,
 }
 
 impl<T> State<T> {
+    /// Creates a new [`State`], initializing the first pane with the provided
+    /// state.
+    ///
+    /// Alongside the [`State`], it returns the first [`Pane`] identifier.
+    ///
+    /// [`State`]: struct.State.html
+    /// [`Pane`]: struct.Pane.html
     pub fn new(first_pane_state: T) -> (Self, Pane) {
         let first_pane = Pane(0);
 
@@ -40,22 +69,42 @@ impl<T> State<T> {
         )
     }
 
+    /// Returns the total amount of panes in the [`State`].
+    ///
+    /// [`State`]: struct.State.html
     pub fn len(&self) -> usize {
         self.panes.len()
     }
 
+    /// Returns the internal state of the given [`Pane`], if it exists.
+    ///
+    /// [`Pane`]: struct.Pane.html
     pub fn get_mut(&mut self, pane: &Pane) -> Option<&mut T> {
         self.panes.get_mut(pane)
     }
 
+    /// Returns an iterator over all the panes of the [`State`], alongside its
+    /// internal state.
+    ///
+    /// [`State`]: struct.State.html
     pub fn iter(&self) -> impl Iterator<Item = (&Pane, &T)> {
         self.panes.iter()
     }
 
+    /// Returns a mutable iterator over all the panes of the [`State`],
+    /// alongside its internal state.
+    ///
+    /// [`State`]: struct.State.html
     pub fn iter_mut(&mut self) -> impl Iterator<Item = (&Pane, &mut T)> {
         self.panes.iter_mut()
     }
 
+    /// Returns the active [`Pane`] of the [`State`], if there is one.
+    ///
+    /// A [`Pane`] is active if it is focused and is __not__ being dragged.
+    ///
+    /// [`Pane`]: struct.Pane.html
+    /// [`State`]: struct.State.html
     pub fn active(&self) -> Option<Pane> {
         match self.internal.action {
             Action::Idle { focus } => focus,
@@ -63,6 +112,27 @@ impl<T> State<T> {
         }
     }
 
+    /// Returns the adjacent [`Pane`] of another [`Pane`] in the given
+    /// direction, if there is one.
+    ///
+    /// ## Example
+    /// You can combine this with [`State::active`] to find the pane that is
+    /// adjacent to the current active one, and then swap them. For instance:
+    ///
+    /// ```
+    /// # use iced_native::pane_grid;
+    /// #
+    /// # let (mut state, _) = pane_grid::State::new(());
+    /// #
+    /// if let Some(active) = state.active() {
+    ///     if let Some(adjacent) = state.adjacent(&active, pane_grid::Direction::Right) {
+    ///         state.swap(&active, &adjacent);
+    ///     }
+    /// }
+    /// ```
+    ///
+    /// [`Pane`]: struct.Pane.html
+    /// [`State::active`]: struct.State.html#method.active
     pub fn adjacent(&self, pane: &Pane, direction: Direction) -> Option<Pane> {
         let regions =
             self.internal.layout.regions(0.0, Size::new(4096.0, 4096.0));
@@ -94,10 +164,18 @@ impl<T> State<T> {
         Some(*pane)
     }
 
+    /// Focuses the given [`Pane`].
+    ///
+    /// [`Pane`]: struct.Pane.html
     pub fn focus(&mut self, pane: &Pane) {
         self.internal.focus(pane);
     }
 
+    /// Splits the given [`Pane`] into two in the given [`Axis`] and
+    /// initializing the new [`Pane`] with the provided internal state.
+    ///
+    /// [`Pane`]: struct.Pane.html
+    /// [`Axis`]: enum.Axis.html
     pub fn split(&mut self, axis: Axis, pane: &Pane, state: T) -> Option<Pane> {
         let node = self.internal.layout.find(pane)?;
 
@@ -121,6 +199,14 @@ impl<T> State<T> {
         Some(new_pane)
     }
 
+    /// Swaps the position of the provided panes in the [`State`].
+    ///
+    /// If you want to swap panes on drag and drop in your [`PaneGrid`], you
+    /// will need to call this method when handling a [`DragEvent`].
+    ///
+    /// [`State`]: struct.State.html
+    /// [`PaneGrid`]: struct.PaneGrid.html
+    /// [`DragEvent`]: struct.DragEvent.html
     pub fn swap(&mut self, a: &Pane, b: &Pane) {
         self.internal.layout.update(&|node| match node {
             Node::Split { .. } => {}
@@ -134,10 +220,24 @@ impl<T> State<T> {
         });
     }
 
-    pub fn resize(&mut self, split: &Split, percentage: f32) {
-        let _ = self.internal.layout.resize(split, percentage);
+    /// Resizes two panes by setting the position of the provided [`Split`].
+    ///
+    /// The ratio is a value in [0, 1], representing the exact position of a
+    /// [`Split`] between two panes.
+    ///
+    /// If you want to enable resize interactions in your [`PaneGrid`], you will
+    /// need to call this method when handling a [`ResizeEvent`].
+    ///
+    /// [`Split`]: struct.Split.html
+    /// [`PaneGrid`]: struct.PaneGrid.html
+    /// [`ResizeEvent`]: struct.ResizeEvent.html
+    pub fn resize(&mut self, split: &Split, ratio: f32) {
+        let _ = self.internal.layout.resize(split, ratio);
     }
 
+    /// Closes the given [`Pane`] and returns its internal state, if it exists.
+    ///
+    /// [`Pane`]: struct.Pane.html
     pub fn close(&mut self, pane: &Pane) -> Option<T> {
         if let Some(sibling) = self.internal.layout.remove(pane) {
             self.focus(&sibling);