docs: Make an attempt

Author: epage

src/level.rs

@@ -1,33 +1,41 @@
+//! [`Level`] constants for easy importing
+
 use crate::renderer::stylesheet::Stylesheet;
 use crate::snippet::{ERROR_TXT, HELP_TXT, INFO_TXT, NOTE_TXT, WARNING_TXT};
 use crate::{Element, Group, Message, Title};
 use anstyle::Style;
 
+/// Default `error:` [`Level`]
 pub const ERROR: Level<'_> = Level {
     name: None,
     level: LevelInner::Error,
 };
 
+/// Default `warning:` [`Level`]
 pub const WARNING: Level<'_> = Level {
     name: None,
     level: LevelInner::Warning,
 };
 
+/// Default `info:` [`Level`]
 pub const INFO: Level<'_> = Level {
     name: None,
     level: LevelInner::Info,
 };
 
+/// Default `note:` [`Level`]
 pub const NOTE: Level<'_> = Level {
     name: None,
     level: LevelInner::Note,
 };
 
+/// Default `help:` [`Level`]
 pub const HELP: Level<'_> = Level {
     name: None,
     level: LevelInner::Help,
 };
 
+/// [`Message`] or [`Title`] severity level
 #[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord)]
 pub struct Level<'a> {
     pub(crate) name: Option<Option<&'a str>>,
@@ -41,9 +49,13 @@ impl<'a> Level<'a> {
     pub const NOTE: Level<'a> = NOTE;
     pub const HELP: Level<'a> = HELP;
 
+    /// <div class="warning">
+    ///
     /// Text passed to this function is considered "untrusted input", as such
     /// all text is passed through a normalization function. Pre-styled text is
     /// not allowed to be passed to this function.
+    ///
+    /// </div>
     pub fn text(self, text: Option<&'a str>) -> Level<'a> {
         Level {
             name: Some(text),
@@ -53,9 +65,13 @@ impl<'a> Level<'a> {
 }
 
 impl<'a> Level<'a> {
+    /// <div class="warning">
+    ///
     /// Text passed to this function is considered "untrusted input", as such
     /// all text is passed through a normalization function. Pre-styled text is
     /// not allowed to be passed to this function.
+    ///
+    /// </div>
     pub fn header(self, header: &'a str) -> Message<'a> {
         Message {
             id: None,
@@ -67,10 +83,14 @@ impl<'a> Level<'a> {
         }
     }
 
+    /// <div class="warning">
+    ///
     /// Text passed to this function is allowed to be pre-styled, as such all
     /// text is considered "trusted input" and has no normalizations applied to
     /// it. [`normalize_untrusted_str`](crate::normalize_untrusted_str) can be
     /// used to normalize untrusted text before it is passed to this function.
+    ///
+    /// </div>
     pub fn title(self, title: &'a str) -> Title<'a> {
         Title {
             level: self,

src/snippet.rs

@@ -10,18 +10,27 @@ pub(crate) const INFO_TXT: &str = "info";
 pub(crate) const NOTE_TXT: &str = "note";
 pub(crate) const WARNING_TXT: &str = "warning";
 
+/// Top-level user message
 #[derive(Debug)]
 pub struct Message<'a> {
     pub(crate) id: Option<&'a str>, // for "correctness", could be sloppy and be on Title
     pub(crate) groups: Vec<Group<'a>>,
 }
 
 impl<'a> Message<'a> {
+    /// <div class="warning">
+    ///
+    /// Text passed to this function is considered "untrusted input", as such
+    /// all text is passed through a normalization function. Pre-styled text is
+    /// not allowed to be passed to this function.
+    ///
+    /// </div>
     pub fn id(mut self, id: &'a str) -> Self {
         self.id = Some(id);
         self
     }
 
+    /// Add an [`Element`] container
     pub fn group(mut self, group: Group<'a>) -> Self {
         self.groups.push(group);
         self
@@ -66,6 +75,7 @@ impl<'a> Message<'a> {
     }
 }
 
+/// An [`Element`] container
 #[derive(Debug)]
 pub struct Group<'a> {
     pub(crate) elements: Vec<Element<'a>>,
@@ -97,6 +107,7 @@ impl<'a> Group<'a> {
     }
 }
 
+/// A section of content within a [`Group`]
 #[derive(Debug)]
 #[non_exhaustive]
 pub enum Element<'a> {
@@ -137,9 +148,13 @@ impl From<Padding> for Element<'_> {
     }
 }
 
+/// A whitespace [`Element`] in a [`Group`]
 #[derive(Debug)]
 pub struct Padding;
 
+/// A text [`Element`] in a [`Group`]
+///
+/// See [`Level::title`] to create this.
 #[derive(Debug)]
 pub struct Title<'a> {
     pub(crate) level: Level<'a>,
@@ -154,6 +169,7 @@ impl Title<'_> {
     }
 }
 
+/// A source view [`Element`] in a [`Group`]
 #[derive(Debug)]
 pub struct Snippet<'a, T> {
     pub(crate) origin: Option<&'a str>,
@@ -164,9 +180,15 @@ pub struct Snippet<'a, T> {
 }
 
 impl<'a, T: Clone> Snippet<'a, T> {
+    /// The source code to be rendered
+    ///
+    /// <div class="warning">
+    ///
     /// Text passed to this function is considered "untrusted input", as such
     /// all text is passed through a normalization function. Pre-styled text is
     /// not allowed to be passed to this function.
+    ///
+    /// </div>
     pub fn source(source: &'a str) -> Self {
         Self {
             origin: None,
@@ -177,49 +199,65 @@ impl<'a, T: Clone> Snippet<'a, T> {
         }
     }
 
+    /// When manually [`fold`][Self::fold]ing,
+    /// the [`source`][Self::source]s line offset from the original start
     pub fn line_start(mut self, line_start: usize) -> Self {
         self.line_start = line_start;
         self
     }
 
+    /// The location of the [`source`][Self::source] (e.g. a path)
+    ///
+    /// <div class="warning">
+    ///
     /// Text passed to this function is considered "untrusted input", as such
     /// all text is passed through a normalization function. Pre-styled text is
     /// not allowed to be passed to this function.
+    ///
+    /// </div>
     pub fn origin(mut self, origin: &'a str) -> Self {
         self.origin = Some(origin);
         self
     }
 
+    /// Hide lines without [`Annotation`]s
     pub fn fold(mut self, fold: bool) -> Self {
         self.fold = fold;
         self
     }
 }
 
 impl<'a> Snippet<'a, Annotation<'a>> {
+    /// Highlight and describe a span of text within the [`source`][Self::source]
     pub fn annotation(mut self, annotation: Annotation<'a>) -> Snippet<'a, Annotation<'a>> {
         self.markers.push(annotation);
         self
     }
 
+    /// Highlight and describe spans of text within the [`source`][Self::source]
     pub fn annotations(mut self, annotation: impl IntoIterator<Item = Annotation<'a>>) -> Self {
         self.markers.extend(annotation);
         self
     }
 }
 
 impl<'a> Snippet<'a, Patch<'a>> {
+    /// Suggest to the user an edit to the [`source`][Self::source]
     pub fn patch(mut self, patch: Patch<'a>) -> Snippet<'a, Patch<'a>> {
         self.markers.push(patch);
         self
     }
 
+    /// Suggest to the user edits to the [`source`][Self::source]
     pub fn patches(mut self, patches: impl IntoIterator<Item = Patch<'a>>) -> Self {
         self.markers.extend(patches);
         self
     }
 }
 
+/// Highlighted and describe a span of text within a [`Snippet`]
+///
+/// See [`AnnotationKind`] to create an annotation.
 #[derive(Clone, Debug)]
 pub struct Annotation<'a> {
     pub(crate) span: Range<usize>,
@@ -229,20 +267,30 @@ pub struct Annotation<'a> {
 }
 
 impl<'a> Annotation<'a> {
+    /// Describe the reason the span is highlighted
+    ///
+    /// This will be styled according to the [`AnnotationKind`]
+    ///
+    /// <div class="warning">
+    ///
     /// Text passed to this function is considered "untrusted input", as such
     /// all text is passed through a normalization function. Pre-styled text is
     /// not allowed to be passed to this function.
+    ///
+    /// </div>
     pub fn label(mut self, label: &'a str) -> Self {
         self.label = Some(label);
         self
     }
 
+    /// Style the source according to the [`AnnotationKind`]
     pub fn highlight_source(mut self, highlight_source: bool) -> Self {
         self.highlight_source = highlight_source;
         self
     }
 }
 
+/// The category of the [`Annotation`]
 #[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord)]
 pub enum AnnotationKind {
     /// Color to [`Message`]'s [`Level`]
@@ -266,16 +314,23 @@ impl AnnotationKind {
     }
 }
 
+/// Suggested edit to the [`Snippet`]
 #[derive(Clone, Debug)]
 pub struct Patch<'a> {
     pub(crate) span: Range<usize>,
     pub(crate) replacement: &'a str,
 }
 
 impl<'a> Patch<'a> {
+    /// Splice `replacement` into the [`Snippet`] at the `span`
+    ///
+    /// <div class="warning">
+    ///
     /// Text passed to this function is considered "untrusted input", as such
     /// all text is passed through a normalization function. Pre-styled text is
     /// not allowed to be passed to this function.
+    ///
+    /// </div>
     pub fn new(span: Range<usize>, replacement: &'a str) -> Self {
         Self { span, replacement }
     }
@@ -328,6 +383,7 @@ impl<'a> Patch<'a> {
     }
 }
 
+/// The location of the [`Snippet`] (e.g. a path)
 #[derive(Clone, Debug)]
 pub struct Origin<'a> {
     pub(crate) origin: &'a str,
@@ -338,9 +394,13 @@ pub struct Origin<'a> {
 }
 
 impl<'a> Origin<'a> {
+    /// <div class="warning">
+    ///
     /// Text passed to this function is considered "untrusted input", as such
     /// all text is passed through a normalization function. Pre-styled text is
     /// not allowed to be passed to this function.
+    ///
+    /// </div>
     pub fn new(origin: &'a str) -> Self {
         Self {
             origin,
@@ -351,11 +411,17 @@ impl<'a> Origin<'a> {
         }
     }
 
+    /// Set the default line number to display
+    ///
+    /// Otherwise this will be inferred from the primary [`Annotation`]
     pub fn line(mut self, line: usize) -> Self {
         self.line = Some(line);
         self
     }
 
+    /// Set the default column to display
+    ///
+    /// Otherwise this will be inferred from the primary [`Annotation`]
     pub fn char_column(mut self, char_column: usize) -> Self {
         self.char_column = Some(char_column);
         self
@@ -366,9 +432,15 @@ impl<'a> Origin<'a> {
         self
     }
 
+    /// Like [`Annotation::label`], but when there is no source
+    ///
+    /// <div class="warning">
+    ///
     /// Text passed to this function is considered "untrusted input", as such
     /// all text is passed through a normalization function. Pre-styled text is
     /// not allowed to be passed to this function.
+    ///
+    /// </div>
     pub fn label(mut self, label: &'a str) -> Self {
         self.label = Some(label);
         self