Add more documentation (#166)

src/message/html.rs

@@ -37,7 +37,8 @@ use crate::{
     util::{join_cell_text, space_text},
 };
 
-struct BulletIterator {
+/// Generate bullet points from a [ListStyle].
+pub struct BulletIterator {
     style: ListStyle,
     pos: usize,
     len: usize,
@@ -74,6 +75,7 @@ impl Iterator for BulletIterator {
     }
 }
 
+/// Whether this list is ordered or unordered.
 #[derive(Clone, Copy, Debug)]
 pub enum ListStyle {
     Ordered,
@@ -88,11 +90,13 @@ impl ListStyle {
 
 pub type StyleTreeChildren = Vec<StyleTreeNode>;
 
+/// Type of contents in a table cell.
 pub enum CellType {
     Data,
     Header,
 }
 
+/// A collection of cells for a single row in a table.
 pub struct TableRow {
     cells: Vec<(CellType, StyleTreeNode)>,
 }
@@ -103,6 +107,7 @@ impl TableRow {
     }
 }
 
+/// A collection of rows in a table.
 pub struct TableSection {
     rows: Vec<TableRow>,
 }
@@ -113,6 +118,7 @@ impl TableSection {
     }
 }
 
+/// A table.
 pub struct Table {
     caption: Option<Box<StyleTreeNode>>,
     sections: Vec<TableSection>,
@@ -229,6 +235,7 @@ impl Table {
     }
 }
 
+/// A processed HTML element that we can render to the terminal.
 pub enum StyleTreeNode {
     Blockquote(Box<StyleTreeNode>),
     Break,
@@ -380,6 +387,7 @@ impl StyleTreeNode {
     }
 }
 
+/// A processed HTML document.
 pub struct StyleTree {
     children: StyleTreeChildren,
 }
@@ -649,6 +657,7 @@ fn dom_to_style_tree(dom: RcDom) -> StyleTree {
     StyleTree { children: h2t(&dom.document) }
 }
 
+/// Parse an HTML document from a string.
 pub fn parse_matrix_html(s: &str) -> StyleTree {
     let dom = parse_fragment(
         RcDom::default(),

src/message/mod.rs

@@ -1,3 +1,4 @@
+//! # Room Messages
 use std::borrow::Cow;
 use std::cmp::{Ord, Ordering, PartialOrd};
 use std::collections::hash_map::DefaultHasher;

src/message/printer.rs

@@ -1,3 +1,8 @@
+//! # Line Wrapping Logic
+//!
+//! The [TextPrinter] handles wrapping stylized text and inserting spaces for padding at the end of
+//! lines to make concatenation work right (e.g., combining table cells after wrapping their
+//! contents).
 use std::borrow::Cow;
 
 use modalkit::tui::layout::Alignment;
@@ -8,6 +13,7 @@ use unicode_width::UnicodeWidthStr;
 
 use crate::util::{space_span, take_width};
 
+/// Wrap styled text for the current terminal width.
 pub struct TextPrinter<'a> {
     text: Text<'a>,
     width: usize,
@@ -21,6 +27,7 @@ pub struct TextPrinter<'a> {
 }
 
 impl<'a> TextPrinter<'a> {
+    /// Create a new printer.
     pub fn new(width: usize, base_style: Style, hide_reply: bool) -> Self {
         TextPrinter {
             text: Text::default(),
@@ -35,24 +42,29 @@ impl<'a> TextPrinter<'a> {
         }
     }
 
+    /// Configure the alignment for each line.
     pub fn align(mut self, alignment: Alignment) -> Self {
         self.alignment = alignment;
         self
     }
 
+    /// Set whether newlines should be treated literally, or turned into spaces.
     pub fn literal(mut self, literal: bool) -> Self {
         self.literal = literal;
         self
     }
 
+    /// Indicates whether replies should be pushed to the printer.
     pub fn hide_reply(&self) -> bool {
         self.hide_reply
     }
 
+    /// Indicates the current printer's width.
     pub fn width(&self) -> usize {
         self.width
     }
 
+    /// Create a new printer with a smaller width.
     pub fn sub(&self, indent: usize) -> Self {
         TextPrinter {
             text: Text::default(),
@@ -71,6 +83,7 @@ impl<'a> TextPrinter<'a> {
         self.width - self.curr_width
     }
 
+    /// If there is any text on the current line, start a new one.
     pub fn commit(&mut self) {
         if self.curr_width > 0 {
             self.push_break();
@@ -82,6 +95,7 @@ impl<'a> TextPrinter<'a> {
         self.text.lines.push(Spans(std::mem::take(&mut self.curr_spans)));
     }
 
+    /// Start a new line.
     pub fn push_break(&mut self) {
         if self.curr_width == 0 && self.text.lines.is_empty() {
             // Disallow leading breaks.
@@ -149,6 +163,7 @@ impl<'a> TextPrinter<'a> {
         }
     }
 
+    /// Push a [Span] that isn't allowed to break across lines.
     pub fn push_span_nobreak(&mut self, span: Span<'a>) {
         let sw = UnicodeWidthStr::width(span.content.as_ref());
 
@@ -161,6 +176,7 @@ impl<'a> TextPrinter<'a> {
         self.curr_width += sw;
     }
 
+    /// Push text with a [Style].
     pub fn push_str(&mut self, s: &'a str, style: Style) {
         let style = self.base_style.patch(style);
 
@@ -212,16 +228,19 @@ impl<'a> TextPrinter<'a> {
         }
     }
 
+    /// Push [Spans] into the printer.
     pub fn push_line(&mut self, spans: Spans<'a>) {
         self.commit();
         self.text.lines.push(spans);
     }
 
+    /// Push multiline [Text] into the printer.
     pub fn push_text(&mut self, text: Text<'a>) {
         self.commit();
         self.text.lines.extend(text.lines);
     }
 
+    /// Render the contents of this printer as [Text].
     pub fn finish(mut self) -> Text<'a> {
         self.commit();
         self.text