Fix documentation of markdown and rich_text

core/src/lib.rs

@@ -84,3 +84,12 @@ pub use vector::Vector;
 pub use widget::Widget;
 
 pub use smol_str::SmolStr;
+
+/// A function that can _never_ be called.
+///
+/// This is useful to turn generic types into anything
+/// you want by coercing them into a type with no possible
+/// values.
+pub fn never<T>(never: std::convert::Infallible) -> T {
+    match never {}
+}

examples/changelog/src/main.rs

@@ -280,7 +280,7 @@ impl Generator {
                             .font(Font::MONOSPACE);
 
                             let description =
-                                markdown::view(&self.theme(), description)
+                                markdown(description, self.theme())
                                     .map(Message::UrlClicked);
 
                             let labels =
@@ -344,12 +344,12 @@ impl Generator {
                 } else {
                     container(
                         scrollable(
-                            markdown::view(
+                            markdown(
+                                preview,
                                 markdown::Settings::with_text_size(
                                     12,
-                                    &self.theme(),
+                                    self.theme(),
                                 ),
-                                preview,
                             )
                             .map(Message::UrlClicked),
                         )

examples/markdown/src/main.rs

@@ -164,11 +164,11 @@ impl Markdown {
         };
 
         let preview = markdown::view_with(
+            items,
+            &self.theme,
             &MarkdownViewer {
                 images: &self.images,
             },
-            &self.theme,
-            items,
         );
 
         row![

src/lib.rs

@@ -505,9 +505,9 @@ pub use crate::core::gradient;
 pub use crate::core::padding;
 pub use crate::core::theme;
 pub use crate::core::{
-    Alignment, Animation, Background, Border, Color, ContentFit, Degrees,
+    never, Alignment, Animation, Background, Border, Color, ContentFit,
-    Gradient, Length, Padding, Pixels, Point, Radians, Rectangle, Rotation,
+    Degrees, Gradient, Length, Padding, Pixels, Point, Radians, Rectangle,
-    Settings, Shadow, Size, Theme, Transformation, Vector,
+    Rotation, Settings, Shadow, Size, Theme, Transformation, Vector,
 };
 pub use crate::runtime::exit;
 pub use iced_futures::Subscription;

widget/src/helpers.rs

@@ -167,7 +167,7 @@ macro_rules! text {
 /// # pub type Element<'a, Message> = iced_widget::core::Element<'a, Message, iced_widget::Theme, iced_widget::Renderer>;
 /// use iced::font;
 /// use iced::widget::{rich_text, span};
-/// use iced::{color, Font};
+/// use iced::{color, never, Font};
 ///
 /// #[derive(Debug, Clone)]
 /// enum Message {
@@ -177,9 +177,10 @@ macro_rules! text {
 /// fn view(state: &State) -> Element<'_, Message> {
 ///     rich_text![
 ///         span("I am red!").color(color!(0xff0000)),
-///         " ",
+///         span(" "),
 ///         span("And I am bold!").font(Font { weight: font::Weight::Bold, ..Font::default() }),
 ///     ]
+///     .on_link_clicked(never)
 ///     .size(20)
 ///     .into()
 /// }
@@ -1138,10 +1139,11 @@ where
 /// # pub type Element<'a, Message> = iced_widget::core::Element<'a, Message, iced_widget::Theme, iced_widget::Renderer>;
 /// use iced::font;
 /// use iced::widget::{rich_text, span};
-/// use iced::{color, Font};
+/// use iced::{color, never, Font};
 ///
 /// #[derive(Debug, Clone)]
 /// enum Message {
+///     LinkClicked(&'static str),
 ///     // ...
 /// }
 ///
@@ -1151,6 +1153,7 @@ where
 ///         span(" "),
 ///         span("And I am bold!").font(Font { weight: font::Weight::Bold, ..Font::default() }),
 ///     ])
+///     .on_link_clicked(never)
 ///     .size(20)
 ///     .into()
 /// }
@@ -1181,7 +1184,7 @@ where
 /// # pub type Element<'a, Message> = iced_widget::core::Element<'a, Message, iced_widget::Theme, iced_widget::Renderer>;
 /// use iced::font;
 /// use iced::widget::{rich_text, span};
-/// use iced::{color, Font};
+/// use iced::{color, never, Font};
 ///
 /// #[derive(Debug, Clone)]
 /// enum Message {
@@ -1194,6 +1197,7 @@ where
 ///         " ",
 ///         span("And I am bold!").font(Font { weight: font::Weight::Bold, ..Font::default() }),
 ///     ]
+///     .on_link_clicked(never)
 ///     .size(20)
 ///     .into()
 /// }

widget/src/markdown.rs

@@ -29,11 +29,7 @@
 //!     }
 //!
 //!     fn view(&self) -> Element<'_, Message> {
-//!         markdown::view(
+//!         markdown::view(&self.markdown, Theme::TokyoNight)
-//!             &self.markdown,
-//!             markdown::Settings::default(),
-//!             markdown::Style::from_palette(Theme::TokyoNightStorm.palette()),
-//!         )
 //!             .map(Message::LinkClicked)
 //!             .into()
 //!     }
@@ -47,7 +43,6 @@
 //!     }
 //! }
 //! ```
-#![allow(missing_docs)]
 use crate::core::border;
 use crate::core::font::{self, Font};
 use crate::core::padding;
@@ -334,11 +329,7 @@ impl Span {
 ///     }
 ///
 ///     fn view(&self) -> Element<'_, Message> {
-///         markdown::view(
+///         markdown::view(&self.markdown, Theme::TokyoNight)
-///             &self.markdown,
-///             markdown::Settings::default(),
-///             markdown::Style::from_palette(Theme::TokyoNightStorm.palette()),
-///         )
 ///            .map(Message::LinkClicked)
 ///            .into()
 ///     }
@@ -867,6 +858,12 @@ impl From<&Theme> for Settings {
     }
 }
 
+impl From<Theme> for Settings {
+    fn from(theme: Theme) -> Self {
+        Self::with_style(Style::from(theme))
+    }
+}
+
 /// The text styling of some Markdown rendering in [`view`].
 #[derive(Debug, Clone, Copy, PartialEq)]
 pub struct Style {
@@ -907,6 +904,12 @@ impl From<&Theme> for Style {
     }
 }
 
+impl From<Theme> for Style {
+    fn from(theme: Theme) -> Self {
+        Self::from_palette(theme.palette())
+    }
+}
+
 /// Display a bunch of Markdown items.
 ///
 /// You can obtain the items with [`parse`].
@@ -935,11 +938,7 @@ impl From<&Theme> for Style {
 ///     }
 ///
 ///     fn view(&self) -> Element<'_, Message> {
-///         markdown::view(
+///         markdown::view(&self.markdown, Theme::TokyoNight)
-///             &self.markdown,
-///             markdown::Settings::default(),
-///             markdown::Style::from_palette(Theme::TokyoNightStorm.palette()),
-///         )
 ///             .map(Message::LinkClicked)
 ///             .into()
 ///     }
@@ -954,28 +953,25 @@ impl From<&Theme> for Style {
 /// }
 /// ```
 pub fn view<'a, Theme, Renderer>(
-    settings: impl Into<Settings>,
     items: impl IntoIterator<Item = &'a Item>,
+    settings: impl Into<Settings>,
 ) -> Element<'a, Url, Theme, Renderer>
 where
     Theme: Catalog + 'a,
     Renderer: core::text::Renderer<Font = Font> + 'a,
 {
-    view_with(&DefaultViewer, settings, items)
+    view_with(items, settings, &DefaultViewer)
 }
 
-/// Runs [`view`] but with a custom [`View`] to turn an [`Item`] into
+/// Runs [`view`] but with a custom [`Viewer`] to turn an [`Item`] into
 /// an [`Element`].
 ///
 /// This is useful if you want to customize the look of certain Markdown
 /// elements.
-///
-/// You can use [`Item::view`] and [`Item::view_with`] for the default
-/// look.
 pub fn view_with<'a, Message, Theme, Renderer>(
-    viewer: &impl Viewer<'a, Message, Theme, Renderer>,
-    settings: impl Into<Settings>,
     items: impl IntoIterator<Item = &'a Item>,
+    settings: impl Into<Settings>,
+    viewer: &impl Viewer<'a, Message, Theme, Renderer>,
 ) -> Element<'a, Message, Theme, Renderer>
 where
     Message: 'a,
@@ -992,6 +988,7 @@ where
     Element::new(column(blocks).spacing(settings.spacing))
 }
 
+/// Displays an [`Item`] using the given [`Viewer`].
 pub fn item<'a, Message, Theme, Renderer>(
     viewer: &impl Viewer<'a, Message, Theme, Renderer>,
     settings: Settings,
@@ -1006,7 +1003,7 @@ where
     match item {
         Item::Image { title, url } => viewer.image(settings, title, url),
         Item::Heading(level, text) => {
-            viewer.heading(settings, index, level, text)
+            viewer.heading(settings, level, text, index)
         }
         Item::Paragraph(text) => viewer.paragraph(settings, text),
         Item::CodeBlock(lines) => viewer.code_block(settings, lines),
@@ -1020,11 +1017,12 @@ where
     }
 }
 
+/// Displays a heading using the default look.
 pub fn heading<'a, Message, Theme, Renderer>(
     settings: Settings,
-    index: usize,
     level: &'a HeadingLevel,
     text: &'a Text,
+    index: usize,
     on_link_clicked: impl Fn(Url) -> Message + 'a,
 ) -> Element<'a, Message, Theme, Renderer>
 where
@@ -1063,6 +1061,7 @@ where
     .into()
 }
 
+/// Displays a paragraph using the default look.
 pub fn paragraph<'a, Message, Theme, Renderer>(
     settings: Settings,
     text: &'a Text,
@@ -1079,6 +1078,8 @@ where
         .into()
 }
 
+/// Displays an unordered list using the default look and
+/// calling the [`Viewer`] for each bullet point item.
 pub fn unordered_list<'a, Message, Theme, Renderer>(
     viewer: &impl Viewer<'a, Message, Theme, Renderer>,
     settings: Settings,
@@ -1093,12 +1094,12 @@ where
         row![
             text("•").size(settings.text_size),
             view_with(
-                viewer,
+                items,
                 Settings {
                     spacing: settings.spacing * 0.6,
                     ..settings
                 },
-                items,
+                viewer,
             )
         ]
         .spacing(settings.spacing)
@@ -1109,6 +1110,8 @@ where
     .into()
 }
 
+/// Displays an ordered list using the default look and
+/// calling the [`Viewer`] for each numbered item.
 pub fn ordered_list<'a, Message, Theme, Renderer>(
     viewer: &impl Viewer<'a, Message, Theme, Renderer>,
     settings: Settings,
@@ -1124,12 +1127,12 @@ where
         row![
             text!("{}.", i as u64 + start).size(settings.text_size),
             view_with(
-                viewer,
+                items,
                 Settings {
                     spacing: settings.spacing * 0.6,
                     ..settings
                 },
-                items,
+                viewer,
             )
         ]
         .spacing(settings.spacing)
@@ -1140,6 +1143,7 @@ where
     .into()
 }
 
+/// Displays a code block using the default look.
 pub fn code_block<'a, Message, Theme, Renderer>(
     settings: Settings,
     lines: &'a [Text],
@@ -1181,8 +1185,12 @@ where
     Theme: Catalog + 'a,
     Renderer: core::text::Renderer<Font = Font> + 'a,
 {
+    /// Produces a message when a link is clicked with the given [`Url`].
     fn on_link_clicked(url: Url) -> Message;
 
+    /// Displays an image.
+    ///
+    /// By default, it will show a container with the image title.
     fn image(
         &self,
         settings: Settings,
@@ -1200,16 +1208,22 @@ where
         .into()
     }
 
+    /// Displays a heading.
+    ///
+    /// By default, it calls [`heading`].
     fn heading(
         &self,
         settings: Settings,
-        index: usize,
         level: &'a HeadingLevel,
         text: &'a Text,
+        index: usize,
     ) -> Element<'a, Message, Theme, Renderer> {
-        heading(settings, index, level, text, Self::on_link_clicked)
+        heading(settings, level, text, index, Self::on_link_clicked)
     }
 
+    /// Displays a paragraph.
+    ///
+    /// By default, it calls [`paragraph`].
     fn paragraph(
         &self,
         settings: Settings,
@@ -1218,6 +1232,9 @@ where
         paragraph(settings, text, Self::on_link_clicked)
     }
 
+    /// Displays a code block.
+    ///
+    /// By default, it calls [`code_block`].
     fn code_block(
         &self,
         settings: Settings,
@@ -1226,6 +1243,9 @@ where
         code_block(settings, lines, Self::on_link_clicked)
     }
 
+    /// Displays an unordered list.
+    ///
+    /// By default, it calls [`unordered_list`].
     fn unordered_list(
         &self,
         settings: Settings,
@@ -1234,6 +1254,9 @@ where
         unordered_list(self, settings, items)
     }
 
+    /// Displays an ordered list.
+    ///
+    /// By default, it calls [`ordered_list`].
     fn ordered_list(
         &self,
         settings: Settings,