doc: everything

3 files changed, 38 insertions, 15 deletions

diff --git a/src/writer.rs b/src/writer.rs
index 40a935b..c30f03e 100644
--- a/src/writer.rs
+++ b/src/writer.rs
@@ -9,14 +9,17 @@ use web_sys::WebSocket;
 use crate::{
     declaration::{Declaration, VersionInfo},
     element::{escape_str, Content, Element, IntoContent, IntoElement, Name, NamespaceDeclaration},
-    endable::Endable,
     error::Error,
-    loggable::Loggable,
     xml::{self, composers::Composer, parsers_complete::Parser},
     Result, XMLNS_NS, XML_NS,
 };
+use endable::Endable;
+use loggable::Loggable;
 
-// pub struct Writer<W, C = Composer> {
+mod endable;
+mod loggable;
+
+/// Writer that tracks depth and corresponding declared/available namespaces.
 #[derive(Debug)]
 pub struct Writer<W> {
     inner: Endable<W>,
@@ -26,6 +29,7 @@ pub struct Writer<W> {
 }
 
 impl<W> Writer<Loggable<W>> {
+    /// Create a new `Writer` which is constrained to a single root element.
     pub fn new(writer: W) -> Self {
         let mut default_declarations = HashSet::new();
         default_declarations.insert(NamespaceDeclaration {
@@ -44,6 +48,7 @@ impl<W> Writer<Loggable<W>> {
         }
     }
 
+    /// Create a new `Writer` which is not constrained to a single root element.
     pub fn new_unendable(writer: W) -> Self {
         let mut default_declarations = HashSet::new();
         default_declarations.insert(NamespaceDeclaration {
@@ -62,6 +67,7 @@ impl<W> Writer<Loggable<W>> {
         }
     }
 
+    /// Extract the inner type from the `Writer`.
     pub fn into_inner(self) -> W {
         self.inner.into_inner().into_inner()
     }
@@ -69,6 +75,7 @@ impl<W> Writer<Loggable<W>> {
 
 #[cfg(target_arch = "wasm32")]
 impl Writer<WebSocket> {
+    /// Create a new `Writer` which is constrained to a single root element.
     pub fn new(websocket: WebSocket) -> Self {
         let mut default_declarations = HashSet::new();
         default_declarations.insert(NamespaceDeclaration {
@@ -87,10 +94,12 @@ impl Writer<WebSocket> {
         }
     }
 
+    /// Extract the inner `WebSocket` from the `Writer`.
     pub fn into_inner(self) -> WebSocket {
         self.inner.into_inner()
     }
 
+    /// Create a new `Writer` which is not constrained to a single root element.
     pub fn new_unendable(websocket: WebSocket) -> Self {
         let mut default_declarations = HashSet::new();
         default_declarations.insert(NamespaceDeclaration {
@@ -109,6 +118,7 @@ impl Writer<WebSocket> {
         }
     }
 
+    /// Write an XML declaration with the provided `VersionInfo`.
     pub async fn write_declaration(&mut self, version: VersionInfo) -> Result<()> {
         let declaration = Declaration::version(version);
         let version_info;
@@ -132,6 +142,7 @@ impl Writer<WebSocket> {
         Ok(())
     }
 
+    /// Write a full element corresponding with the item implementing `IntoElement` (start tag + content + end tag).
     pub async fn write_full(&mut self, into_element: &impl IntoElement) -> Result<()> {
         let element = into_element.into_element();
         let mut frame = String::new();
@@ -141,6 +152,7 @@ impl Writer<WebSocket> {
         Ok(())
     }
 
+    /// Write the start tag of an item that implements `IntoElement`. Navigates up the document.
     pub async fn write_start(&mut self, into_element: &impl IntoElement) -> Result<()> {
         let element = into_element.into_element();
         let mut frame = String::new();
@@ -150,6 +162,7 @@ impl Writer<WebSocket> {
         Ok(())
     }
 
+    /// Write all the inner content (everything within the start and end tag of an xml element) of an item that implements `IntoElement`. In the case of an empty element, write nothing.
     pub async fn write_all_content(&mut self, into_element: &impl IntoElement) -> Result<()> {
         let mut frame = String::new();
         for content in &into_element.get_content() {
@@ -160,6 +173,7 @@ impl Writer<WebSocket> {
         Ok(())
     }
 
+    /// Write an item that implements `IntoContent`. Could be an element, some text, a comment, etc. Anything that could be included in an element body.
     pub async fn write(&mut self, into_content: &impl IntoContent) -> Result<()> {
         let content = into_content.into_content();
         let mut frame = String::new();
@@ -169,7 +183,7 @@ impl Writer<WebSocket> {
         Ok(())
     }
 
-    // pub async fn write_end(&mut self)
+    /// Navigate down the document structure and write the end tag for the current element opened in the document context.
     pub async fn write_end(&mut self) -> Result<()> {
         let mut frame = String::new();
         self.write_end_tag_to_frame(&mut frame)?;
@@ -178,7 +192,7 @@ impl Writer<WebSocket> {
         Ok(())
     }
 
-    pub fn write_element_to_frame(&mut self, element: &Element, frame: &mut String) -> Result<()> {
+    fn write_element_to_frame(&mut self, element: &Element, frame: &mut String) -> Result<()> {
         if element.content.is_empty() {
             self.write_empty_to_frame(element, frame)?;
         } else {
@@ -191,8 +205,8 @@ impl Writer<WebSocket> {
         Ok(())
     }
 
-    pub fn write_empty_to_frame(&mut self, element: &Element, frame: &mut String) -> Result<()> {
-        let writer = if self.unendable {
+    fn write_empty_to_frame(&mut self, element: &Element, frame: &mut String) -> Result<()> {
+        let _writer = if self.unendable {
             self.inner.ignore_end()
         } else {
             self.inner.try_as_mut()?
@@ -306,12 +320,12 @@ impl Writer<WebSocket> {
         Ok(())
     }
 
-    pub fn write_element_start_to_frame(
+    fn write_element_start_to_frame(
         &mut self,
         element: &Element,
         frame: &mut String,
     ) -> Result<()> {
-        let writer = if self.unendable {
+        let _writer = if self.unendable {
             self.inner.ignore_end()
         } else {
             self.inner.try_as_mut()?
@@ -424,11 +438,11 @@ impl Writer<WebSocket> {
         Ok(())
     }
 
-    pub fn write_content_to_frame(&mut self, content: &Content, frame: &mut String) -> Result<()> {
+    fn write_content_to_frame(&mut self, content: &Content, frame: &mut String) -> Result<()> {
         match content {
             Content::Element(element) => self.write_element_to_frame(element, frame)?,
             Content::Text(text) => {
-                let writer = if self.unendable {
+                let _writer = if self.unendable {
                     self.inner.ignore_end()
                 } else {
                     self.inner.try_as_mut()?
@@ -442,8 +456,8 @@ impl Writer<WebSocket> {
         Ok(())
     }
 
-    pub fn write_end_tag_to_frame(&mut self, frame: &mut String) -> Result<()> {
-        let writer = if self.unendable {
+    fn write_end_tag_to_frame(&mut self, frame: &mut String) -> Result<()> {
+        let _writer = if self.unendable {
             self.inner.ignore_end()
         } else {
             self.inner.try_as_mut()?
@@ -491,8 +505,8 @@ impl Writer<WebSocket> {
     }
 }
 
-#[cfg(not(target_arch = "wasm32"))]
 impl<W: AsyncWrite + Unpin + Send> Writer<Loggable<W>> {
+    /// Write an XML declaration with the provided `VersionInfo`.
     pub async fn write_declaration(&mut self, version: VersionInfo) -> Result<()> {
         let writer = if self.unendable {
             self.inner.ignore_end()
@@ -516,6 +530,7 @@ impl<W: AsyncWrite + Unpin + Send> Writer<Loggable<W>> {
         Ok(())
     }
 
+    /// Write a full element corresponding with the item implementing `IntoElement` (start tag + content + end tag).
     pub async fn write_full(&mut self, into_element: &impl IntoElement) -> Result<()> {
         let element = into_element.into_element();
         self.write_element(&element).await?;
@@ -525,6 +540,7 @@ impl<W: AsyncWrite + Unpin + Send> Writer<Loggable<W>> {
         Ok(())
     }
 
+    /// Write the start tag of an item that implements `IntoElement`. Navigates up the document.
     pub async fn write_start(&mut self, into_element: &impl IntoElement) -> Result<()> {
         let element = into_element.into_element();
         self.write_element_start(&element).await?;
@@ -534,6 +550,7 @@ impl<W: AsyncWrite + Unpin + Send> Writer<Loggable<W>> {
         Ok(())
     }
 
+    /// Write all the inner content (everything within the start and end tag of an xml element) of an item that implements `IntoElement`. In the case of an empty element, write nothing.
     pub async fn write_all_content(&mut self, into_element: &impl IntoElement) -> Result<()> {
         for content in &into_element.get_content() {
             self.write_content(content).await?;
@@ -544,6 +561,7 @@ impl<W: AsyncWrite + Unpin + Send> Writer<Loggable<W>> {
         Ok(())
     }
 
+    /// Write an item that implements `IntoContent`. Could be an element, some text, a comment, etc. Anything that could be included in an element body.
     pub async fn write(&mut self, into_content: &impl IntoContent) -> Result<()> {
         let content = into_content.into_content();
         self.write_content(&content).await?;
@@ -553,7 +571,7 @@ impl<W: AsyncWrite + Unpin + Send> Writer<Loggable<W>> {
         Ok(())
     }
 
-    // pub async fn write_end(&mut self)
+    /// Navigate down the document structure and write the end tag for the current element opened in the document context.
     pub async fn write_end(&mut self) -> Result<()> {
         self.write_end_tag().await?;
         let bytes = &self.inner.ignore_end().take_log();
@@ -563,6 +581,7 @@ impl<W: AsyncWrite + Unpin + Send> Writer<Loggable<W>> {
     }
 
     #[async_recursion]
+    /// Write an `Element`.
     pub async fn write_element(&mut self, element: &Element) -> Result<()> {
         if element.content.is_empty() {
             self.write_empty(element).await?;
@@ -576,6 +595,7 @@ impl<W: AsyncWrite + Unpin + Send> Writer<Loggable<W>> {
         Ok(())
     }
 
+    /// Write an empty element tag from an `Element` (ignoring any content).
     pub async fn write_empty(&mut self, element: &Element) -> Result<()> {
         let writer = if self.unendable {
             self.inner.ignore_end()
@@ -690,6 +710,7 @@ impl<W: AsyncWrite + Unpin + Send> Writer<Loggable<W>> {
         Ok(())
     }
 
+    /// Write an element start tag from an `Element`, navigating up in document depth.
     pub async fn write_element_start(&mut self, element: &Element) -> Result<()> {
         let writer = if self.unendable {
             self.inner.ignore_end()
@@ -803,6 +824,7 @@ impl<W: AsyncWrite + Unpin + Send> Writer<Loggable<W>> {
         Ok(())
     }
 
+    /// Write some `Content`.
     pub async fn write_content(&mut self, content: &Content) -> Result<()> {
         match content {
             Content::Element(element) => self.write_element(element).await?,
@@ -821,6 +843,7 @@ impl<W: AsyncWrite + Unpin + Send> Writer<Loggable<W>> {
         Ok(())
     }
 
+    /// Write an end tag (depending on the current document context), moving back down in the document.
     pub async fn write_end_tag(&mut self) -> Result<()> {
         let writer = if self.unendable {
             self.inner.ignore_end()
diff --git a/src/endable.rs b/src/writer/endable.rs
index 6d842f3..6d842f3 100644
--- a/src/endable.rs
+++ b/src/writer/endable.rs
diff --git a/src/loggable.rs b/src/writer/loggable.rs
index dd69668..dd69668 100644
--- a/src/loggable.rs
+++ b/src/writer/loggable.rs