Add missing docs + release 1.2.0 (#196)

* Add missing docs for public API.

Make StartTag::encoding non-public

* Release 1.2.0

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## v1.2.0
+
+- Expose `is_self_closing` and `can_have_content` in C api.
+- Make `ElementContentHandlers` and `DocumentContentHandlers` fields public.
+- Add missing docs to public API.
+
 ## v1.1.1
 
 ### Fixed

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "lol_html"
-version = "1.1.1"
+version = "1.2.0"
 authors = ["Ivan Nikulin <inikulin@cloudflare.com, ifaaan@gmail.com>"]
 license = "BSD-3-Clause"
 description = "Streaming HTML rewriter/parser with CSS selector-based API"

src/html/text_type.rs

@@ -37,6 +37,9 @@ pub enum TextType {
 }
 
 impl TextType {
+    /// Returns `true` if the text type allows [HTML entities].
+    ///
+    /// [HTML entities]: https://developer.mozilla.org/en-US/docs/Glossary/Entity
     #[inline]
     pub fn allows_html_entities(self) -> bool {
         self == TextType::Data || self == TextType::RCData

src/lib.rs

@@ -17,8 +17,7 @@
 //! [`HtmlRewriter`]: struct.HtmlRewriter.html
 //! [`rewrite_str`]: fn.rewrite_str.html
 
-// TODO Uncomment this once we have all items documented.
-// #![cfg_attr(not(any(feature = "integration_test", test)), warn(missing_docs))]
+#![cfg_attr(not(any(feature = "integration_test", test)), warn(missing_docs))]
 
 #[macro_use]
 mod base;

src/rewritable_units/element.rs

@@ -179,7 +179,7 @@ impl<'r, 't> Element<'r, 't> {
 
     /// Sets `value` of element's attribute with `name`.
     ///
-    /// If element doesn't have an attribute with the `name`, method adds new attribute
+    /// If element doesn't have an attribute with the `name`, method adds a new attribute
     /// to the element with `name` and `value`.
     #[inline]
     pub fn set_attribute(&mut self, name: &str, value: &str) -> Result<(), AttributeNameError> {

src/rewritable_units/tokens/end_tag.rs

@@ -4,6 +4,9 @@ use crate::rewritable_units::ContentType;
 use encoding_rs::Encoding;
 use std::fmt::{self, Debug};
 
+/// An HTML end tag rewritable unit.
+///
+/// Exposes API for examination and modification of a parsed HTML end tag.
 pub struct EndTag<'i> {
     name: Bytes<'i>,
     raw: Option<Bytes<'i>>,
@@ -37,12 +40,14 @@ impl<'i> EndTag<'i> {
         self.name.as_string(self.encoding)
     }
 
+    /// Sets the name of the tag.
     #[inline]
     pub fn set_name(&mut self, name: Bytes<'static>) {
         self.name = name;
         self.raw = None;
     }
 
+    /// Sets the name of the tag by encoding the given string.
     #[inline]
     pub fn set_name_str(&mut self, name: String) {
         self.set_name(Bytes::from_string(name, self.encoding))

src/rewritable_units/tokens/start_tag.rs

@@ -6,6 +6,9 @@ use crate::rewritable_units::ContentType;
 use encoding_rs::Encoding;
 use std::fmt::{self, Debug};
 
+/// An HTML start tag rewritable unit.
+///
+/// Exposes API for examination and modification of a parsed HTML start tag.
 pub struct StartTag<'i> {
     name: Bytes<'i>,
     attributes: Attributes<'i>,
@@ -37,6 +40,7 @@ impl<'i> StartTag<'i> {
     }
 
     #[inline]
+    #[doc(hidden)]
     pub fn encoding(&self) -> &'static Encoding {
         self.encoding
     }
@@ -53,22 +57,31 @@ impl<'i> StartTag<'i> {
         self.name.as_string(self.encoding)
     }
 
+    /// Sets the name of the tag.
     #[inline]
     pub fn set_name(&mut self, name: Bytes<'static>) {
         self.name = name;
         self.raw = None;
     }
 
+    /// Returns the [namespace URI] of the tag's element.
+    ///
+    /// [namespace URI]: https://developer.mozilla.org/en-US/docs/Web/API/Element/namespaceURI
     #[inline]
     pub fn namespace_uri(&self) -> &'static str {
         self.ns.uri()
     }
 
+    /// Returns an immutable collection of tag's attributes.
     #[inline]
     pub fn attributes(&self) -> &[Attribute<'i>] {
         &self.attributes
     }
 
+    /// Sets `value` of tag's attribute with `name`.
+    ///
+    /// If tag doesn't have an attribute with the `name`, method adds a new attribute
+    /// to the tag with `name` and `value`.
     #[inline]
     pub fn set_attribute(&mut self, name: &str, value: &str) -> Result<(), AttributeNameError> {
         self.attributes.set_attribute(name, value, self.encoding)?;
@@ -77,13 +90,15 @@ impl<'i> StartTag<'i> {
         Ok(())
     }
 
+    /// Removes an attribute with the `name` if it is present.
     #[inline]
     pub fn remove_attribute(&mut self, name: &str) {
         if self.attributes.remove_attribute(name) {
             self.raw = None;
         }
     }
 
+    /// Whether the tag is explicitly self-closing, e.g. `<foo />`.
     #[inline]
     pub fn self_closing(&self) -> bool {
         self.self_closing

src/rewriter/mod.rs

@@ -45,6 +45,7 @@ impl AsciiCompatibleEncoding {
             .and_then(AsciiCompatibleEncoding::new)
     }
 
+    /// Returns the most commonly used UTF-8 encoding.
     pub fn utf_8() -> AsciiCompatibleEncoding {
         Self(encoding_rs::UTF_8)
     }

src/rewriter/settings.rs

@@ -533,6 +533,11 @@ pub struct Settings<'h, 's> {
     /// `true` when constructed with `Settings::default()`.
     pub strict: bool,
 
+    /// If enabled the rewriter enables support for [Edge Side Includes] tags, treating them as
+    /// [void elements] and allowing them to be replaced with desired content.
+    ///
+    /// [Edge Side Includes]: https://www.w3.org/TR/esi-lang/
+    /// [void elements]: https://developer.mozilla.org/en-US/docs/Glossary/Void_element
     pub enable_esi_tags: bool,
 
     /// If enabled the rewriter will dynamically change the charset when it encounters a `meta` tag
@@ -683,6 +688,11 @@ pub struct RewriteStrSettings<'h, 's> {
     /// `true` when constructed with `Settings::default()`.
     pub strict: bool,
 
+    /// If enabled the rewriter enables support for [Edge Side Includes] tags, treating them as
+    /// [void elements] and allowing them to be replaced with desired content.
+    ///
+    /// [Edge Side Includes]: https://www.w3.org/TR/esi-lang/
+    /// [void elements]: https://developer.mozilla.org/en-US/docs/Glossary/Void_element
     pub enable_esi_tags: bool,
 }