diff options
author | Lars Wirzenius <liw@liw.fi> | 2022-12-04 11:38:37 +0200 |
---|---|---|
committer | Lars Wirzenius <liw@liw.fi> | 2022-12-04 11:38:37 +0200 |
commit | ba8f157bb0b08bd04ec78b952550b1a22b9862db (patch) | |
tree | b23d4de54113e835e892ee0a54d5406d2d842055 | |
parent | 35ce15a89637083b4794e7fc2621c477fb073638 (diff) | |
download | riki-ba8f157bb0b08bd04ec78b952550b1a22b9862db.tar.gz |
docs: add docstrings to html module
Sponsored-by: author
-rw-r--r-- | src/html.rs | 29 |
1 files changed, 29 insertions, 0 deletions
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. |