docs(title): add documentation to title (#443)

This adds documentation for Title and Position

src/title.rs

@@ -1,25 +1,93 @@
+#![warn(missing_docs)]
+//! This module holds the [`Title`] element and its related configuration types.
+//! A title is a piece of [`Block`](crate::widgets::Block) configuration.
+
 use strum::{Display, EnumString};
 
 use crate::{layout::Alignment, text::Line};
 
+/// A [`Block`](crate::widgets::Block) title.
+///
+/// It can be aligned (see [`Alignment`]) and positioned (see [`Position`]).
+///
+/// # Example
+///
+/// Title with no style.
+/// ```
+/// # use ratatui::widgets::block::Title;
+/// Title::from("Title");
+/// ```
+///
+/// Blue title on a white background (via [`Stylize`](crate::style::Stylize) trait).
+/// ```
+/// # use ratatui::widgets::block::Title;
+/// # use ratatui::style::Stylize;
+/// Title::from("Title".blue().on_white());
+/// ```
+///
+/// Title with multiple styles (see [`Line`] and [`Stylize`](crate::style::Stylize)).
+/// ```
+/// # use ratatui::widgets::block::Title;
+/// # use ratatui::style::Stylize;
+/// # use ratatui::text::Line;
+/// Title::from(
+///     Line::from(vec!["Q".white().underlined(), "uit".gray()])
+/// );
+/// ```
+///
+/// Complete example
+/// ```
+/// # use ratatui::widgets::block::{Title, Position};
+/// # use ratatui::layout::Alignment;
+/// Title::from("Title")
+///     .position(Position::Top)
+///     .alignment(Alignment::Right);
+/// ```
 #[derive(Debug, Default, Clone, Eq, PartialEq, Hash)]
 pub struct Title<'a> {
+    /// Title content
     pub content: Line<'a>,
-    /// Defaults to Left if unset
+    /// Title alignment
+    ///
+    /// If [`None`], defaults to the alignment defined with
+    /// [`Block::title_alignment`](crate::widgets::Block::title_alignment) in the associated
+    /// [`Block`](crate::widgets::Block).
     pub alignment: Option<Alignment>,
 
-    /// Defaults to Top if unset
+    /// Title position
+    ///
+    /// If [`None`], defaults to the position defined with
+    /// [`Block::title_position`](crate::widgets::Block::title_position) in the associated
+    /// [`Block`](crate::widgets::Block).
     pub position: Option<Position>,
 }
 
+/// Defines the [title](crate::widgets::block::Title) position.
+///
+/// The title can be positioned on top or at the bottom of the block.
+/// Defaults to [`Position::Top`].
+///
+/// # Example
+///
+/// ```
+/// # use ratatui::widgets::{Block, block::{Title, Position}};
+/// Block::new().title(
+///     Title::from("title").position(Position::Bottom)
+/// );
+/// ```
 #[derive(Debug, Default, Display, EnumString, Clone, Copy, PartialEq, Eq, Hash)]
 pub enum Position {
+    /// Position the title at the top of the block.
+    ///
+    /// This is the default.
     #[default]
     Top,
+    /// Position the title at the bottom of the block.
     Bottom,
 }
 
 impl<'a> Title<'a> {
+    /// Builder pattern method for setting the title content.
     pub fn content<T>(mut self, content: T) -> Title<'a>
     where
         T: Into<Line<'a>>,
@@ -28,11 +96,13 @@ impl<'a> Title<'a> {
         self
     }
 
+    /// Builder pattern method for setting the title alignment.
     pub fn alignment(mut self, alignment: Alignment) -> Title<'a> {
         self.alignment = Some(alignment);
         self
     }
 
+    /// Builder pattern method for setting the title position.
     pub fn position(mut self, position: Position) -> Title<'a> {
         self.position = Some(position);
         self