From ba8f157bb0b08bd04ec78b952550b1a22b9862db Mon Sep 17 00:00:00 2001
From: Lars Wirzenius <liw@liw.fi>
Date: Sun, 4 Dec 2022 11:38:37 +0200
Subject: docs: add docstrings to html module

Sponsored-by: author
---
 src/html.rs | 29 +++++++++++++++++++++++++++++
 1 file changed, 29 insertions(+)

diff --git a/src/html.rs b/src/html.rs
index d023ba4..e550ba7 100644
--- a/src/html.rs
+++ b/src/html.rs
@@ -1,3 +1,7 @@
+//! A representation of HTML using Rust types.
+
+#![deny(missing_docs)]
+
 use html_escape::{encode_double_quoted_attribute, encode_text};
 use line_col::LineColLookup;
 use log::{debug, trace};
@@ -6,6 +10,7 @@ use std::fmt::Write as _;
 use std::io::Write;
 use std::path::{Path, PathBuf};
 
+/// A HTML page, consisting of a head and a body.
 #[derive(Debug)]
 pub struct HtmlPage {
     head: Element,
@@ -22,18 +27,22 @@ impl Default for HtmlPage {
 }
 
 impl HtmlPage {
+    /// Create a new HTML page from a head and a body element.
     pub fn new(head: Element, body: Element) -> Self {
         Self { head, body }
     }
 
+    /// Return the page's head element.
     pub fn head(&self) -> &Element {
         &self.head
     }
 
+    /// Return the page's body element.
     pub fn body(&self) -> &Element {
         &self.body
     }
 
+    /// Try to serialize an HTML page into HTML text.
     pub fn serialize(&self) -> Result<String, HtmlError> {
         let mut html = Element::new(ElementTag::Html);
         html.push_child(Content::Elt(self.head.clone()));
@@ -41,6 +50,7 @@ impl HtmlPage {
         html.serialize()
     }
 
+    /// Try to write an HTML page as text into a file.
     pub fn write(&self, filename: &Path) -> Result<(), HtmlError> {
         if let Some(parent) = filename.parent() {
             trace!("parent: {}", parent.display());
@@ -61,6 +71,7 @@ impl HtmlPage {
     }
 }
 
+/// Parse Markdown text into an HTML element.
 pub fn parse(markdown: &str) -> Result<Element, HtmlError> {
     let mut options = Options::empty();
     options.insert(Options::ENABLE_HEADING_ATTRIBUTES);
@@ -205,6 +216,7 @@ fn as_plain_text(content: &[Content]) -> String {
     buf
 }
 
+/// An HTML element.
 #[derive(Debug, Clone)]
 pub struct Element {
     loc: Option<Location>,
@@ -214,6 +226,7 @@ pub struct Element {
 }
 
 impl Element {
+    /// Create a new element.
     pub fn new(tag: ElementTag) -> Self {
         Self {
             loc: None,
@@ -232,14 +245,17 @@ impl Element {
         self.attrs.push(attr);
     }
 
+    /// Append a new child to the element.
     pub fn push_child(&mut self, child: Content) {
         self.children.push(child);
     }
 
+    /// Return an element's tag.
     pub fn tag(&self) -> ElementTag {
         self.tag
     }
 
+    /// Return all the children of an element.
     pub fn children(&self) -> &[Content] {
         &self.children
     }
@@ -258,6 +274,7 @@ impl Element {
         }
     }
 
+    /// Serialize an element into HTML text.
     pub fn serialize(&self) -> Result<String, HtmlError> {
         let mut buf = String::new();
         self.serialize_to_buf_without_added_newlines(&mut buf)
@@ -310,7 +327,9 @@ impl Element {
     }
 }
 
+/// The tag of an HTML element.
 #[derive(Copy, Clone, Debug, Eq, PartialEq)]
+#[allow(missing_docs)]
 pub enum ElementTag {
     Html,
     Head,
@@ -402,6 +421,7 @@ impl ElementTag {
     }
 }
 
+/// An attribute of an HTML element.
 #[derive(Clone, Debug)]
 pub struct Attribute {
     name: String,
@@ -416,19 +436,27 @@ impl Attribute {
         }
     }
 
+    /// Return the name of the attribute.
     pub fn name(&self) -> &str {
         &self.name
     }
 
+    /// Return the value of the attribute, if any.
     pub fn value(&self) -> Option<&str> {
         self.value.as_deref()
     }
 }
 
+/// Content in HTML.
 #[derive(Clone, Debug)]
 pub enum Content {
+    /// Arbitrary text.
     Text(String),
+
+    /// An HTML element.
     Elt(Element),
+
+    /// Arbitrary HTML text.
     Html(String),
 }
 
@@ -488,6 +516,7 @@ impl Stack {
     }
 }
 
+/// Errors from the `html` module.
 #[derive(Debug, thiserror::Error)]
 pub enum HtmlError {
     /// Failed to create a directory.
-- 
cgit v1.2.1