chore(doc): add documentation for a handful of widgets

src/widget/aspect_ratio.rs

@@ -1,3 +1,5 @@
+//! A container which constraints itself to a specific aspect ratio.
+
 use iced::widget::Container;
 use iced::Size;
 use iced_core::alignment;
@@ -21,9 +23,7 @@ where
     AspectRatio::new(content, ratio)
 }
 
-/// An element decorating some content.
-///
-/// It is normally used for alignment purposes.
+/// A container which constraints itself to a specific aspect ratio.
 #[allow(missing_debug_implementations)]
 pub struct AspectRatio<'a, Message, Renderer>
 where

src/widget/button/icon.rs

@@ -13,12 +13,14 @@ use std::borrow::Cow;
 
 pub type Button<'a, Message> = Builder<'a, Message, Icon>;
 
+/// The icon variant of a button.
 pub struct Icon {
     handle: Handle,
     vertical: bool,
     selected: bool,
 }
 
+/// A button constructed from an icon handle, using icon button styling.
 pub fn icon<'a, Message>(handle: impl Into<Handle>) -> Button<'a, Message> {
     Button::new(Icon {
         handle: handle.into(),

src/widget/button/image.rs

@@ -11,6 +11,7 @@ use std::borrow::Cow;
 
 pub type Button<'a, Message> = Builder<'a, Message, Image<'a, Handle, Message>>;
 
+/// A button constructed from an image handle, using image button styling.
 pub fn image<'a, Message>(handle: impl Into<Handle> + 'a) -> Button<'a, Message> {
     Button::new(Image {
         image: widget::image(handle).border_radius([9.0; 4]),
@@ -19,6 +20,7 @@ pub fn image<'a, Message>(handle: impl Into<Handle> + 'a) -> Button<'a, Message>
     })
 }
 
+/// The image variant of a button.
 pub struct Image<'a, Handle, Message> {
     image: widget::Image<'a, Handle>,
     selected: bool,

src/widget/button/link.rs

@@ -1,6 +1,8 @@
 // Copyright 2023 System76 <info@system76.com>
 // SPDX-License-Identifier: MPL-2.0
 
+//! Hyperlink button widget
+
 use super::Builder;
 use super::Style;
 use crate::prelude::*;
@@ -17,6 +19,7 @@ pub struct Hyperlink {
     trailing_icon: bool,
 }
 
+/// A hyperlink button.
 pub fn link<'a, Message>(label: impl Into<Cow<'a, str>> + 'static) -> Button<'a, Message> {
     Button::new(
         label,

src/widget/button/mod.rs

@@ -1,29 +1,41 @@
 // Copyright 2023 System76 <info@system76.com>
 // SPDX-License-Identifier: MPL-2.0
 
+//! Button widgets for COSMIC applications.
+
 pub use crate::theme::Button as Style;
 
 pub mod link;
 use derive_setters::Setters;
+#[doc(inline)]
 pub use link::link;
+#[doc(inline)]
 pub use link::Button as LinkButton;
 
 mod icon;
+#[doc(inline)]
 pub use icon::icon;
+#[doc(inline)]
 pub use icon::Button as IconButton;
 
 mod image;
+#[doc(inline)]
 pub use image::image;
+#[doc(inline)]
 pub use image::Button as ImageButton;
 
 mod style;
+#[doc(inline)]
 pub use style::{Appearance, StyleSheet};
 
 mod text;
+#[doc(inline)]
 pub use text::Button as TextButton;
+#[doc(inline)]
 pub use text::{destructive, standard, suggested, text};
 
 mod widget;
+#[doc(inline)]
 pub use widget::{draw, focus, layout, mouse_interaction, Button};
 
 use iced_core::font::Weight;
@@ -31,10 +43,12 @@ use iced_core::widget::Id;
 use iced_core::{Length, Padding};
 use std::borrow::Cow;
 
+/// A button with the default style, which may contain any widget as its content.
 pub fn button<'a, Message>(content: impl Into<crate::Element<'a, Message>>) -> Button<'a, Message> {
     Button::new(content)
 }
 
+/// An image button which may contain any widget as its content.
 pub fn custom_image_button<'a, Message>(
     content: impl Into<crate::Element<'a, Message>>,
     on_remove: Option<Message>,
@@ -42,6 +56,7 @@ pub fn custom_image_button<'a, Message>(
     Button::new_image(content, on_remove)
 }
 
+/// A builder for constructing a custom [`Button`].
 #[must_use]
 #[derive(Setters)]
 pub struct Builder<'a, Message, Variant> {

src/widget/button/text.rs

@@ -10,26 +10,31 @@ use std::borrow::Cow;
 
 pub type Button<'a, Message> = Builder<'a, Message, Text>;
 
+/// A text button with the destructive style
 pub fn destructive<'a, Message>(label: impl Into<Cow<'a, str>>) -> Button<'a, Message> {
     Button::new(Text::new())
         .label(label)
         .style(Style::Destructive)
 }
 
+/// A text button with the suggested style
 pub fn suggested<'a, Message>(label: impl Into<Cow<'a, str>>) -> Button<'a, Message> {
     Button::new(Text::new())
         .label(label)
         .style(Style::Suggested)
 }
 
+/// A text button with the standard style
 pub fn standard<'a, Message>(label: impl Into<Cow<'a, str>>) -> Button<'a, Message> {
     Button::new(Text::new()).label(label)
 }
 
+/// A text button with the text style
 pub fn text<'a, Message>(label: impl Into<Cow<'a, str>>) -> Button<'a, Message> {
     Button::new(Text::new()).label(label).style(Style::Text)
 }
 
+/// The text variant of a button.
 pub struct Text {
     pub(super) leading_icon: Option<icon::Handle>,
     pub(super) trailing_icon: Option<icon::Handle>,

src/widget/button/widget.rs

@@ -59,7 +59,7 @@ pub struct Button<'a, Message> {
 
 impl<'a, Message> Button<'a, Message> {
     /// Creates a new [`Button`] with the given content.
-    pub fn new(content: impl Into<crate::Element<'a, Message>>) -> Self {
+    pub(super) fn new(content: impl Into<crate::Element<'a, Message>>) -> Self {
         Self {
             id: Id::unique(),
             #[cfg(feature = "a11y")]

src/widget/calendar.rs

@@ -1,6 +1,8 @@
 // Copyright 2024 System76 <info@system76.com>
 // SPDX-License-Identifier: MPL-2.0
 
+//! A widget that displays an interactive calendar.
+
 use std::cmp;
 
 use crate::iced_core::{Length, Padding};
@@ -8,6 +10,7 @@ use crate::widget::{button, column, grid, icon, row, text, Grid};
 use chrono::{Datelike, Days, Months, NaiveDate, Weekday};
 use iced::alignment::{Horizontal, Vertical};
 
+/// A widget that displays an interactive calendar.
 pub fn calendar<M>(
     selected: &NaiveDate,
     on_select: impl Fn(NaiveDate) -> M + 'static,

src/widget/color_picker/mod.rs

@@ -1,6 +1,8 @@
 // Copyright 2023 System76 <info@system76.com>
 // SPDX-License-Identifier: MPL-2.0
 
+//! Widgets for selecting colors with a color picker.
+
 use std::borrow::Cow;
 use std::rc::Rc;
 use std::sync::atomic::{AtomicBool, Ordering};
@@ -29,9 +31,12 @@ use palette::{FromColor, RgbHue};
 use super::button::StyleSheet;
 use super::divider::horizontal;
 use super::icon::{self, from_name};
-use super::segmented_button::{self, Model, SingleSelect};
+use super::segmented_button::{self, SingleSelect};
 use super::{button, segmented_control, text, text_input, tooltip, Icon};
 
+#[doc(inline)]
+pub use ColorPickerModel as Model;
+
 // TODO is this going to look correct enough?
 lazy_static! {
     pub static ref HSV_RAINBOW: Vec<ColorStop> = (0u16..8)
@@ -64,7 +69,7 @@ pub enum ColorPickerUpdate {
 #[derive(Setters)]
 pub struct ColorPickerModel {
     #[setters(skip)]
-    segmented_model: Model<SingleSelect>,
+    segmented_model: segmented_button::Model<SingleSelect>,
     #[setters(skip)]
     active_color: palette::Hsv,
     #[setters(skip)]
@@ -246,7 +251,7 @@ impl ColorPickerModel {
 #[derive(Setters, Clone)]
 pub struct ColorPickerBuilder<'a, Message> {
     #[setters(skip)]
-    model: &'a Model<SingleSelect>,
+    model: &'a segmented_button::Model<SingleSelect>,
     #[setters(skip)]
     active_color: palette::Hsv,
     #[setters(skip)]
@@ -757,6 +762,7 @@ fn color_to_string(c: palette::Hsv, is_hex: bool) -> String {
     }
 }
 
+/// A button for selecting a color from a color picker.
 pub fn color_button<'a, Message: 'static>(
     on_press: Option<Message>,
     color: Option<Color>,

src/widget/context_drawer/mod.rs

@@ -1,6 +1,8 @@
 // Copyright 2023 System76 <info@system76.com>
 // SPDX-License-Identifier: MPL-2.0
 
+//! An overlayed widget that attaches a toggleable context drawer to the view.
+
 mod overlay;
 
 mod widget;
@@ -8,6 +10,7 @@ pub use widget::ContextDrawer;
 
 use crate::Element;
 
+/// An overlayed widget that attaches a toggleable context drawer to the view.
 pub fn context_drawer<'a, Message: Clone + 'static, Content, Drawer>(
     header: &'a str,
     on_close: Message,

src/widget/dropdown/mod.rs

@@ -2,6 +2,8 @@
 // Copyright 2019 Héctor Ramón, Iced contributors
 // SPDX-License-Identifier: MPL-2.0 AND MIT
 
+//! Displays a list of options in a popover menu on select.
+
 pub mod menu;
 pub use menu::Menu;
 
@@ -10,6 +12,7 @@ pub mod multi;
 mod widget;
 pub use widget::*;
 
+/// Displays a list of options in a popover menu on select.
 pub fn dropdown<'a, S: AsRef<str>, Message: 'a>(
     selections: &'a [S],
     selected: Option<usize>,

src/widget/flex_row/mod.rs

@@ -1,6 +1,8 @@
 // Copyright 2023 System76 <info@system76.com>
 // SPDX-License-Identifier: MPL-2.0
 
+//! Responsively generates rows of widgets based on the dimensions of its children.
+
 pub mod layout;
 pub mod widget;
 
@@ -8,7 +10,7 @@ pub use widget::FlexRow;
 
 use crate::Element;
 
-/// Responsively generates rows and columns of widgets based on its dimmensions.
+/// Responsively generates rows of widgets based on the dimensions of its children.
 pub const fn flex_row<Message>(children: Vec<Element<Message>>) -> FlexRow<Message> {
     FlexRow::new(children)
 }

src/widget/grid/mod.rs

@@ -1,12 +1,14 @@
 // Copyright 2023 System76 <info@system76.com>
 // SPDX-License-Identifier: MPL-2.0
 
+//! Arrange widgets with a grid layout.
+
 pub mod layout;
 pub mod widget;
 
 pub use widget::Grid;
 
-/// Responsively generates rows and columns of widgets based on its dimmensions.
+/// Arrange widgets with a grid layout.
 pub const fn grid<'a, Message>() -> Grid<'a, Message> {
     Grid::new()
 }

src/widget/mod.rs

@@ -1,7 +1,50 @@
 // Copyright 2022 System76 <info@system76.com>
 // SPDX-License-Identifier: MPL-2.0
 
-//! Cosmic-themed widget implementations.
+//! The COSMIC widget library
+//!
+//! This module contains a wide variety of widgets used throughout the COSMIC app ecosystem.
+//!
+//! # Overview
+//!
+//! Add widgets to your application view by calling the modules and functions below.
+//! Widgets are constructed by chaining their property methods using a functional paradigm.
+//! Modules may contain additional functions for constructing different variations of a widget.
+//! Each module will typically have one widget with the same name as the module, which will be re-exported here.
+//!
+//! ```no_run
+//! use cosmic::prelude::*;
+//! use cosmic::{cosmic_theme, theme, widget};
+//!
+//! const REPOSITORY: &str = "https://github.com/pop-os/libcosmic";
+//!
+//! let cosmic_theme::Spacing { space_xxs, .. } = theme::active().cosmic().spacing;
+//!
+//! let link = widget::button::link(REPOSITORY)
+//!     .on_press(Message::LaunchUrl(REPOSITORY))
+//!     .padding(0);
+//!
+//! let content = widget::column()
+//!     .push(widget::icon::from_name("my-app-icon"))
+//!     .push(widget::text::title3("My App Name"))
+//!     .push(link)
+//!     .align_items(Alignment::Center)
+//!     .spacing(space_xxs);
+//! ```
+//!
+//! Widgets may borrow data from your application struct, and should do so to avoid allocating.
+//!
+//! ```no_run
+//! let text = widget::text::body(&self.cached_text);
+//! ```
+//!
+//! Use the [`cosmic::Apply`](crate::Apply) trait to embed widgets into other widgets which accept them.
+//!
+//! ```no_run
+//! let button = widget::icon::from_name("printer-symbolic")
+//!     .apply(widget::button::icon)
+//!     .on_press(Message::Print);
+//! ```
 
 // Re-exports from Iced
 #[doc(inline)]
@@ -73,19 +116,24 @@ pub use context_drawer::{context_drawer, ContextDrawer};
 #[doc(inline)]
 pub use column::{column, Column};
 pub mod column {
+    //! A container which aligns its children in a column.
+
     pub type Column<'a, Message> = iced::widget::Column<'a, Message, crate::Theme, crate::Renderer>;
 
     #[must_use]
+    /// A container which aligns its children in a column.
     pub fn column<'a, Message>() -> Column<'a, Message> {
         Column::new()
     }
 
     #[must_use]
+    /// A pre-allocated [`column`].
     pub fn with_capacity<'a, Message>(capacity: usize) -> Column<'a, Message> {
         Column::with_children(Vec::with_capacity(capacity))
     }
 
     #[must_use]
+    /// A [`column`] that will be assigned a [`Vec`] of children.
     pub fn with_children<Message>(children: Vec<crate::Element<Message>>) -> Column<Message> {
         Column::with_children(children)
     }
@@ -207,20 +255,26 @@ pub use rectangle_tracker::{rectangle_tracker, RectangleTracker};
 
 #[doc(inline)]
 pub use row::{row, Row};
+
 pub mod row {
+    //! A container which aligns its children in a row.
+
     pub type Row<'a, Message> = iced::widget::Row<'a, Message, crate::Theme, crate::Renderer>;
 
     #[must_use]
+    /// A container which aligns its children in a row.
     pub fn row<'a, Message>() -> Row<'a, Message> {
         Row::new()
     }
 
     #[must_use]
+    /// A pre-allocated [`row`].
     pub fn with_capacity<'a, Message>(capacity: usize) -> Row<'a, Message> {
         Row::with_children(Vec::with_capacity(capacity))
     }
 
     #[must_use]
+    /// A [`row`] that will be assigned a [`Vec`] of children.
     pub fn with_children<Message>(children: Vec<crate::Element<Message>>) -> Row<Message> {
         Row::with_children(children)
     }

src/widget/spin_button/mod.rs

@@ -1,6 +1,8 @@
 // Copyright 2022 System76 <info@system76.com>
 // SPDX-License-Identifier: MPL-2.0
 
+//! A control for incremental adjustments of a value.
+
 mod model;
 use std::borrow::Cow;
 
@@ -20,6 +22,7 @@ pub struct SpinButton<'a, Message> {
     on_change: Box<dyn Fn(model::Message) -> Message + 'static>,
 }
 
+/// A control for incremental adjustments of a value.
 pub fn spin_button<'a, Message: 'static>(
     label: impl Into<Cow<'a, str>>,
     on_change: impl Fn(model::Message) -> Message + 'static,