More documentation

Richard Dodd · Richard Dodd · commit ba7e78e9bf5a · 2017-11-13T09:08:42.000Z
diff --git a/markup5ever/rcdom.rs b/markup5ever/rcdom.rs
@@ -84,6 +84,7 @@ pub struct Node {
 }
 
 impl Node {
+    /// Create a new node from its contents
     fn new(data: NodeData) -> Rc<Self> {
         Rc::new(Node {
             data: data,
@@ -99,12 +100,15 @@ pub type Handle = Rc<Node>;
 /// Weak reference to a DOM node, used for parent pointers.
 pub type WeakHandle = Weak<Node>;
 
+/// Append a parentless node to another nodes' children
 fn append(new_parent: &Handle, child: Handle) {
     let previous_parent = child.parent.replace(Some(Rc::downgrade(new_parent)));
+    // Invariant: child cannot have existing parent
     assert!(previous_parent.is_none());
     new_parent.children.borrow_mut().push(child);
 }
 
+/// If the node has a parent, get it and this node's position in its children
 fn get_parent_and_index(target: &Handle) -> Option<(Handle, usize)> {
     if let Some(weak) = target.parent.take() {
         let parent = weak.upgrade().expect("dangling weak pointer");
diff --git a/markup5ever/serialize.rs b/markup5ever/serialize.rs
@@ -6,35 +6,62 @@
 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
+//! Traits for serializing elements. The serializer expects the data to be xml-like (with a name,
+//! and optional children, attrs, text, comments, doctypes, and [processing instructions]). It uses
+//! the visitor pattern, where the serializer and the serializable objects are decoupled and
+//! implement their own traits.
+//!
+//! [processing instructions]: https://en.wikipedia.org/wiki/Processing_Instruction
 
 use QualName;
 use std::io;
 
 //§ serializing-html-fragments
+/// Used as a parameter to `serialize`, telling it if we want to skip the parent.
+/// TODO check: Currently the parameter to `ChildrenOnly` is unused.
 #[derive(Clone, PartialEq)]
 pub enum TraversalScope {
+    /// Include the parent node when serializing.
     IncludeNode,
+    /// Only serialize the children of the node.
     ChildrenOnly(Option<QualName>)
 }
 
+/// Types that can be serialized (according to the xml-like scheme in `Serializer`) implement this
+/// trait.
 pub trait Serialize {
+    /// Take the serializer and call its methods to serialize this type. The type will dictate
+    /// which methods are called and with what parameters.
     fn serialize<S>(&self, serializer: &mut S, traversal_scope: TraversalScope) -> io::Result<()>
     where S: Serializer;
 }
 
+/// Types that are capable of serializing implement this trait
 pub trait Serializer {
+    /// Serialize the start of an element, for example `<div class="test">`.
     fn start_elem<'a, AttrIter>(&mut self, name: QualName, attrs: AttrIter) -> io::Result<()>
     where AttrIter: Iterator<Item=AttrRef<'a>>;
 
+    /// Serialize the end of an element, for example `</div>`.
     fn end_elem(&mut self, name: QualName) -> io::Result<()>;
 
+    /// Serialize a plain text node.
     fn write_text(&mut self, text: &str) -> io::Result<()>;
 
+    /// Serialize a comment node, for example `<!-- comment -->`.
     fn write_comment(&mut self, text: &str) -> io::Result<()>;
 
+    /// Serialize a doctype node, for example `<!doctype html>`.
     fn write_doctype(&mut self, name: &str) -> io::Result<()>;
 
+    /// Serialize a processing instruction node, for example
+    /// `<?xml-stylesheet type="text/xsl" href="style.xsl"?>`.
     fn write_processing_instruction(&mut self, target: &str, data: &str) -> io::Result<()>;
 }
 
+/// A type alias for an attribute name and value (e.g. the `class="test"` in `<div class="test">`
+/// is represented as `(<QualName of type class>, test).
+///
+/// This is used in [`Serializer::start_elem`] where the value being serialized must supply an
+/// iterator over the attributes for the current element
 pub type AttrRef<'a> = (&'a QualName, &'a str);
