Write documentation for new `PaneGrid` API

4 files changed, 63 insertions, 19 deletions

diff --git a/native/src/lib.rs b/native/src/lib.rs
index 86046f63..b67ff2a1 100644
--- a/native/src/lib.rs
+++ b/native/src/lib.rs
@@ -30,8 +30,8 @@
 //! [`Widget`]: widget/trait.Widget.html
 //! [`UserInterface`]: struct.UserInterface.html
 //! [renderer]: renderer/index.html
-//#![deny(missing_docs)]
-//#![deny(missing_debug_implementations)]
+#![deny(missing_docs)]
+#![deny(missing_debug_implementations)]
 #![deny(unused_results)]
 #![forbid(unsafe_code)]
 #![forbid(rust_2018_idioms)]
diff --git a/native/src/widget/pane_grid.rs b/native/src/widget/pane_grid.rs
index 21788e6a..5313e993 100644
--- a/native/src/widget/pane_grid.rs
+++ b/native/src/widget/pane_grid.rs
@@ -30,7 +30,7 @@ pub use title_bar::TitleBar;
 
 use crate::{
     container, keyboard, layout, mouse, row, text, Clipboard, Element, Event,
-    Hasher, Layout, Length, Point, Rectangle, Size, Widget,
+    Hasher, Layout, Length, Point, Rectangle, Size, Vector, Widget,
 };
 
 /// A collection of panes distributed using either vertical or horizontal splits
@@ -273,9 +273,12 @@ where
         if let Some(((pane, content), layout)) = clicked_region.next() {
             match &self.on_drag {
                 Some(on_drag) => {
-                    if let Some(origin) =
-                        content.drag_origin(layout, cursor_position)
-                    {
+                    if content.can_be_picked_at(layout, cursor_position) {
+                        let pane_position = layout.position();
+
+                        let origin = cursor_position
+                            - Vector::new(pane_position.x, pane_position.y);
+
                         self.state.pick_pane(pane, origin);
 
                         messages
@@ -693,6 +696,17 @@ pub trait Renderer:
         cursor_position: Point,
     ) -> Self::Output;
 
+    /// Draws a [`TitleBar`].
+    ///
+    /// It receives:
+    /// - the bounds, style of the [`TitleBar`]
+    /// - the style of the [`TitleBar`]
+    /// - the title of the [`TitleBar`] with its size, font, and bounds
+    /// - the controls of the [`TitleBar`] with their [`Layout`+, if any
+    /// - the cursor position
+    ///
+    /// [`TitleBar`]: struct.TitleBar.html
+    /// [`Layout`]: ../layout/struct.Layout.html
     fn draw_title_bar<Message>(
         &mut self,
         defaults: &Self::Defaults,
diff --git a/native/src/widget/pane_grid/content.rs b/native/src/widget/pane_grid/content.rs
index 55fa4c60..1f5ce640 100644
--- a/native/src/widget/pane_grid/content.rs
+++ b/native/src/widget/pane_grid/content.rs
@@ -1,11 +1,12 @@
 use crate::container;
 use crate::layout;
 use crate::pane_grid::{self, TitleBar};
-use crate::{Clipboard, Element, Event, Hasher, Layout, Point, Size, Vector};
+use crate::{Clipboard, Element, Event, Hasher, Layout, Point, Size};
 
 /// The content of a [`Pane`].
 ///
 /// [`Pane`]: struct.Pane.html
+#[allow(missing_debug_implementations)]
 pub struct Content<'a, Message, Renderer: pane_grid::Renderer> {
     title_bar: Option<TitleBar<'a, Message, Renderer>>,
     body: Element<'a, Message, Renderer>,
@@ -16,6 +17,9 @@ impl<'a, Message, Renderer> Content<'a, Message, Renderer>
 where
     Renderer: pane_grid::Renderer,
 {
+    /// Creates a new [`Content`] with the provided body.
+    ///
+    /// [`Content`]: struct.Content.html
     pub fn new(body: impl Into<Element<'a, Message, Renderer>>) -> Self {
         Self {
             title_bar: None,
@@ -24,6 +28,10 @@ where
         }
     }
 
+    /// Sets the [`TitleBar`] of this [`Content`].
+    ///
+    /// [`TitleBar`]: struct.TitleBar.html
+    /// [`Content`]: struct.Content.html
     pub fn title_bar(
         mut self,
         title_bar: TitleBar<'a, Message, Renderer>,
@@ -45,6 +53,11 @@ impl<'a, Message, Renderer> Content<'a, Message, Renderer>
 where
     Renderer: pane_grid::Renderer,
 {
+    /// Draws the [`Content`] with the provided [`Renderer`] and [`Layout`].
+    ///
+    /// [`Content`]: struct.Content.html
+    /// [`Renderer`]: trait.Renderer.html
+    /// [`Layout`]: ../layout/struct.Layout.html
     pub fn draw(
         &self,
         renderer: &mut Renderer,
@@ -77,24 +90,23 @@ where
         }
     }
 
-    pub fn drag_origin(
+    /// Returns whether the [`Content`] with the given [`Layout`] can be picked
+    /// at the provided cursor position.
+    ///
+    /// [`Content`]: struct.Content.html
+    /// [`Layout`]: ../layout/struct.Layout.html
+    pub fn can_be_picked_at(
         &self,
         layout: Layout<'_>,
         cursor_position: Point,
-    ) -> Option<Point> {
+    ) -> bool {
         if let Some(title_bar) = &self.title_bar {
             let mut children = layout.children();
             let title_bar_layout = children.next().unwrap();
 
-            if title_bar.is_over_draggable(title_bar_layout, cursor_position) {
-                let position = layout.position();
-
-                Some(cursor_position - Vector::new(position.x, position.y))
-            } else {
-                None
-            }
+            title_bar.is_over_pick_area(title_bar_layout, cursor_position)
         } else {
-            None
+            false
         }
     }
 
diff --git a/native/src/widget/pane_grid/title_bar.rs b/native/src/widget/pane_grid/title_bar.rs
index cf5f0a59..775c8a8f 100644
--- a/native/src/widget/pane_grid/title_bar.rs
+++ b/native/src/widget/pane_grid/title_bar.rs
@@ -2,6 +2,10 @@ use crate::layout;
 use crate::pane_grid;
 use crate::{Clipboard, Element, Event, Layout, Point, Rectangle, Size};
 
+/// The title bar of a [`Pane`].
+///
+/// [`Pane`]: struct.Pane.html
+#[allow(missing_debug_implementations)]
 pub struct TitleBar<'a, Message, Renderer: pane_grid::Renderer> {
     title: String,
     title_size: Option<u16>,
@@ -14,6 +18,9 @@ impl<'a, Message, Renderer> TitleBar<'a, Message, Renderer>
 where
     Renderer: pane_grid::Renderer,
 {
+    /// Cretes a new [`TitleBar`] with the given title.
+    ///
+    /// [`TitleBar`]: struct.TitleBar.html
     pub fn new(title: impl Into<String>) -> Self {
         Self {
             title: title.into(),
@@ -26,7 +33,7 @@ where
 
     /// Sets the size of the title of the [`TitleBar`].
     ///
-    /// [`TitleBar`]: struct.Text.html
+    /// [`TitleBar`]: struct.TitleBar.html
     pub fn title_size(mut self, size: u16) -> Self {
         self.title_size = Some(size);
         self
@@ -64,6 +71,11 @@ impl<'a, Message, Renderer> TitleBar<'a, Message, Renderer>
 where
     Renderer: pane_grid::Renderer,
 {
+    /// Draws the [`TitleBar`] with the provided [`Renderer`] and [`Layout`].
+    ///
+    /// [`TitleBar`]: struct.TitleBar.html
+    /// [`Renderer`]: trait.Renderer.html
+    /// [`Layout`]: ../layout/struct.Layout.html
     pub fn draw(
         &self,
         renderer: &mut Renderer,
@@ -118,7 +130,13 @@ where
         }
     }
 
-    pub fn is_over_draggable(
+    /// Returns whether the mouse cursor is over the pick area of the
+    /// [`TitleBar`] or not.
+    ///
+    /// The whole [`TitleBar`] is a pick area, except its controls.
+    ///
+    /// [`TitleBar`]: struct.TitleBar.html
+    pub fn is_over_pick_area(
         &self,
         layout: Layout<'_>,
         cursor_position: Point,