docs(canvas): add documentation to canvas module (#913)

Document the whole `canvas` module. With this, the whole `widgets`
module is documented.

src/widgets.rs

@@ -1,3 +1,4 @@
+#![warn(missing_docs)]
 //! `widgets` is a collection of types that implement [`Widget`] or [`StatefulWidget`] or both.
 //!
 //! Widgets are created for each frame as they are consumed after rendered.
@@ -215,7 +216,12 @@ pub trait Widget {
 /// }
 /// ```
 pub trait StatefulWidget {
+    /// State associated with the stateful widget.
+    ///
+    /// If you don't need this then you probably want to implement [`Widget`] instead.
     type State;
+    /// Draws the current state of the widget in the given buffer. That is the only method required
+    /// to implement a custom stateful widget.
     fn render(self, area: Rect, buf: &mut Buffer, state: &mut Self::State);
 }
 
@@ -290,6 +296,8 @@ pub trait StatefulWidget {
 /// ```
 #[stability::unstable(feature = "widget-ref")]
 pub trait WidgetRef {
+    /// Draws the current state of the widget in the given buffer. That is the only method required
+    /// to implement a custom widget.
     fn render_ref(&self, area: Rect, buf: &mut Buffer);
 }
 
@@ -385,7 +393,12 @@ impl<W: WidgetRef> WidgetRef for Option<W> {
 /// ```
 #[stability::unstable(feature = "widget-ref")]
 pub trait StatefulWidgetRef {
+    /// State associated with the stateful widget.
+    ///
+    /// If you don't need this then you probably want to implement [`WidgetRef`] instead.
     type State;
+    /// Draws the current state of the widget in the given buffer. That is the only method required
+    /// to implement a custom stateful widget.
     fn render_ref(&self, area: Rect, buf: &mut Buffer, state: &mut Self::State);
 }
 

src/widgets/barchart.rs

@@ -1,4 +1,3 @@
-#![warn(missing_docs)]
 use crate::{prelude::*, widgets::Block};
 
 mod bar;

src/widgets/block.rs

@@ -1,4 +1,3 @@
-#![warn(missing_docs)]
 //! Elements related to the `Block` base widget.
 //!
 //! This holds everything needed to display and configure a [`Block`].

src/widgets/canvas/circle.rs

@@ -3,12 +3,16 @@ use crate::{
     widgets::canvas::{Painter, Shape},
 };
 
-/// Shape to draw a circle with a given center and radius and with the given color
+/// A circle with a given center and radius and with a given color
 #[derive(Debug, Default, Clone, PartialEq)]
 pub struct Circle {
+    /// `x` coordinate of the circle's center
     pub x: f64,
+    /// `y` coordinate of the circle's center
     pub y: f64,
+    /// Radius of the circle
     pub radius: f64,
+    /// Color of the circle
     pub color: Color,
 }
 

src/widgets/canvas/line.rs

@@ -3,18 +3,23 @@ use crate::{
     widgets::canvas::{Painter, Shape},
 };
 
-/// Shape to draw a line from (x1, y1) to (x2, y2) with the given color
+/// A line from `(x1, y1)` to `(x2, y2)` with the given color
 #[derive(Debug, Default, Clone, PartialEq)]
 pub struct Line {
+    /// `x` of the starting point
     pub x1: f64,
+    /// `y` of the starting point
     pub y1: f64,
+    /// `x` of the ending point
     pub x2: f64,
+    /// `y` of the ending point
     pub y2: f64,
+    /// Color of the line
     pub color: Color,
 }
 
 impl Line {
-    /// Create a new line from (x1, y1) to (x2, y2) with the given color
+    /// Create a new line from `(x1, y1)` to `(x2, y2)` with the given color
     pub fn new(x1: f64, y1: f64, x2: f64, y2: f64, color: Color) -> Self {
         Self {
             x1,

src/widgets/canvas/map.rs

@@ -8,10 +8,21 @@ use crate::{
     },
 };
 
+/// Defines how many points are going to be used to draw a [`Map`].
+///
+/// You generally want a [high](MapResolution::High) resolution map.
 #[derive(Debug, Default, Display, EnumString, Clone, Copy, Eq, PartialEq, Hash)]
 pub enum MapResolution {
+    /// A lesser resolution for the [`Map`] [`Shape`].
+    ///
+    /// Contains about 1000 points.
     #[default]
     Low,
+    /// A higher resolution for the [`Map`] [`Shape`].
+    ///
+    /// Contains about 5000 points, you likely want to use [`Marker::Braille`] with this.
+    ///
+    /// [`Marker::Braille`]: (crate::symbols::Marker::Braille)
     High,
 }
 
@@ -24,10 +35,18 @@ impl MapResolution {
     }
 }
 
-/// Shape to draw a world map with the given resolution and color
+/// A world map
+///
+/// A world map can be rendered with different [resolutions](MapResolution) and [colors](Color).
 #[derive(Debug, Default, Clone, Eq, PartialEq, Hash)]
 pub struct Map {
+    /// The resolution of the map.
+    ///
+    /// This is the number of points used to draw the map.
     pub resolution: MapResolution,
+    /// Map color
+    ///
+    /// This is the color of the points of the map.
     pub color: Color,
 }
 

src/widgets/canvas/points.rs

@@ -3,10 +3,12 @@ use crate::{
     widgets::canvas::{Painter, Shape},
 };
 
-/// A shape to draw a group of points with the given color
+/// A group of points with a given color
 #[derive(Debug, Default, Clone, PartialEq)]
 pub struct Points<'a> {
+    /// List of points to draw
     pub coords: &'a [(f64, f64)],
+    /// Color of the points
     pub color: Color,
 }
 

src/widgets/canvas/rectangle.rs

@@ -3,13 +3,25 @@ use crate::{
     widgets::canvas::{Line, Painter, Shape},
 };
 
-/// Shape to draw a rectangle from a `Rect` with the given color
+/// A rectangle to draw on a [`Canvas`](super::Canvas)
+///
+/// Sizes used here are **not** in terminal cell. This is much more similar to the
+/// mathematic coordinate system.
 #[derive(Debug, Default, Clone, PartialEq)]
 pub struct Rectangle {
+    /// The `x` position of the rectangle.
+    ///
+    /// The rectangle is positioned from its bottom left corner.
     pub x: f64,
+    /// The `y` position of the rectangle.
+    ///
+    /// The rectangle is positioned from its bottom left corner.
     pub y: f64,
+    /// The width of the rectangle.
     pub width: f64,
+    /// The height of the rectangle.
     pub height: f64,
+    /// The color of the rectangle.
     pub color: Color,
 }
 

src/widgets/chart.rs

@@ -1,4 +1,3 @@
-#![warn(missing_docs)]
 use std::cmp::max;
 
 use strum::{Display, EnumString};

src/widgets/gauge.rs

@@ -1,5 +1,3 @@
-#![deny(missing_docs)]
-
 use crate::{prelude::*, widgets::Block};
 
 /// A widget to display a progress bar.

src/widgets/list.rs

@@ -1,4 +1,3 @@
-#![warn(missing_docs)]
 use strum::{Display, EnumString};
 use unicode_width::UnicodeWidthStr;
 

src/widgets/scrollbar.rs

@@ -1,4 +1,3 @@
-#![warn(missing_docs)]
 use std::iter;
 
 use strum::{Display, EnumString};

src/widgets/sparkline.rs

@@ -1,4 +1,3 @@
-#![warn(missing_docs)]
 use std::cmp::min;
 
 use strum::{Display, EnumString};

src/widgets/table.rs

@@ -1,5 +1,3 @@
-#![warn(missing_docs)]
-
 use strum::{Display, EnumString};
 
 mod cell;

src/widgets/tabs.rs

@@ -1,4 +1,3 @@
-#![deny(missing_docs)]
 use crate::{prelude::*, widgets::Block};
 
 const DEFAULT_HIGHLIGHT_STYLE: Style = Style::new().add_modifier(Modifier::REVERSED);