Docs and cleanups.

rocket/src/main.rs

@@ -9,10 +9,9 @@ use rocket::response::{Responder, Result};
 use rocket::{get, routes, Request, Response};
 use std::io::Cursor;
 use typed_html::types::LinkType;
-use typed_html::{dom::Node, text};
-use typed_html_macros::html;
+use typed_html::{dom::DOMTree, html, text};
 
-struct Html(Box<Node<String>>);
+struct Html(DOMTree<String>);
 
 impl<'r> Responder<'r> for Html {
     fn respond_to(self, _request: &Request) -> Result<'r> {

typed-html/Cargo.toml

@@ -9,7 +9,6 @@ strum = "0.11.0"
 strum_macros = "0.11.0"
 mime = "0.3.12"
 language-tags = "0.2.2"
-enumset = "0.3.12"
 http = "0.1.13"
 htmlescape = "0.3.1"
 stdweb = "0.4.10"

typed-html/src/bin/main.rs

@@ -3,11 +3,10 @@
 
 #[macro_use]
 extern crate typed_html;
-extern crate typed_html_macros;
 
 use typed_html::dom::TextNode;
+use typed_html::html;
 use typed_html::types::*;
-use typed_html_macros::html;
 
 struct Foo {
     foo: &'static str,

typed-html/src/dom.rs

@@ -8,6 +8,26 @@ use elements::{FlowContent, PhrasingContent};
 use events::Events;
 use htmlescape::encode_minimal;
 
+/// A boxed DOM tree, as returned from the `html!` macro.
+///
+/// # Examples
+///
+/// ```
+/// # #![feature(proc_macro_hygiene)]
+/// # extern crate typed_html;
+/// # use typed_html::html;
+/// # use typed_html::dom::DOMTree;
+/// # fn main() {
+/// let tree: DOMTree<String> = html!(
+///     <div class="hello">
+///         <p>"Hello Joe!"</p>
+///     </div>
+/// );
+/// let rendered_tree: String = tree.to_string();
+/// # }
+/// ```
+pub type DOMTree<T> = Box<Node<T>>;
+
 /// An untyped representation of an HTML node.
 ///
 /// This structure is designed to be easily walked in order to render a DOM tree
@@ -52,7 +72,7 @@ pub trait Node<T: OutputType>: Display {
     /// Render the node into a [`VNode`][VNode] tree.
     ///
     /// [VNode]: enum.VNode.html
-    fn vnode<'a>(&'a mut self) -> VNode<'a, T>;
+    fn vnode(&mut self) -> VNode<T>;
 }
 
 /// Trait for querying a typed HTML element.

typed-html/src/events.rs

@@ -25,6 +25,26 @@ macro_rules! declare_events {
             }
         }
 
+        /// Iterate over the defined events on a DOM object.
+        ///
+        /// # Examples
+        ///
+        /// ```
+        /// # #![feature(proc_macro_hygiene)]
+        /// # extern crate typed_html;
+        /// # use typed_html::{html, for_events};
+        /// # use typed_html::dom::{DOMTree, VNode};
+        /// # fn main() {
+        /// let mut doc: DOMTree<String> = html!(
+        ///     <button onclick="alert('clicked!')"/>
+        /// );
+        /// if let VNode::Element(element) = doc.vnode() {
+        ///     for_events!(event in element.events => {
+        ///         assert_eq!("alert('clicked!')", event.render().unwrap());
+        ///     });
+        /// }
+        /// # }
+        /// ```
         #[macro_export]
         macro_rules! for_events {
             ($event:ident in $events:expr => $body:block) => {

typed-html/src/lib.rs

@@ -1,7 +1,5 @@
 #![feature(try_from)]
 
-#[macro_use]
-extern crate enumset;
 #[macro_use]
 extern crate strum_macros;
 
@@ -13,6 +11,8 @@ extern crate stdweb;
 extern crate strum;
 extern crate typed_html_macros;
 
+pub use typed_html_macros::html;
+
 pub mod dom;
 pub mod elements;
 pub mod events;

typed-html/src/types/class.rs

@@ -5,13 +5,22 @@ use std::str::FromStr;
 
 use super::Id;
 
+/// A valid CSS class.
+///
+/// A CSS class is a non-empty string that starts with an alphanumeric character
+/// and is followed by any number of alphanumeric characters and the
+/// `_`, `-` and `.` characters.
+///
+/// See also [`Id`][Id].
+///
+/// [Id]: struct.Id.html
 #[derive(Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Debug)]
 pub struct Class(String);
 
 impl Class {
-    // Construct a new class name from a string.
-    //
-    // Returns `None` if the provided string is invalid.
+    /// Construct a new class name from a string.
+    ///
+    /// Returns `Err` if the provided string is invalid.
     pub fn try_new<S: Into<String>>(id: S) -> Result<Self, &'static str> {
         let id = id.into();
         {
@@ -34,9 +43,9 @@ impl Class {
         Ok(Class(id))
     }
 
-    // Construct a new class name from a string.
-    //
-    // Panics if the provided string is invalid.
+    /// Construct a new class name from a string.
+    ///
+    /// Panics if the provided string is invalid.
     pub fn new<S: Into<String>>(id: S) -> Self {
         let id = id.into();
         Self::try_new(id.clone()).unwrap_or_else(|err| {

typed-html/src/types/id.rs

@@ -5,13 +5,22 @@ use std::str::FromStr;
 
 use super::Class;
 
+/// A valid HTML ID.
+///
+/// An ID is a non-empty string that starts with an alphanumeric character
+/// and is followed by any number of alphanumeric characters and the
+/// `_`, `-` and `.` characters.
+///
+/// See also [`Class`][Class].
+///
+/// [Class]: struct.Class.html
 #[derive(Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Debug)]
 pub struct Id(String);
 
 impl Id {
-    // Construct a new ID from a string.
-    //
-    // Returns `None` if the provided string is invalid.
+    /// Construct a new ID from a string.
+    ///
+    /// Returns `Err` if the provided string is invalid.
     pub fn try_new<S: Into<String>>(id: S) -> Result<Self, &'static str> {
         let id = id.into();
         {
@@ -32,9 +41,9 @@ impl Id {
         Ok(Id(id))
     }
 
-    // Construct a new ID from a string.
-    //
-    // Panics if the provided string is invalid.
+    /// Construct a new ID from a string.
+    ///
+    /// Panics if the provided string is invalid.
     pub fn new<S: Into<String>>(id: S) -> Self {
         let id = id.into();
         Self::try_new(id.clone()).unwrap_or_else(|err| {

typed-html/src/types/mod.rs

@@ -25,8 +25,7 @@ pub type Integrity = String;
 pub type Nonce = String;
 pub type Target = String;
 
-enum_set_type! {
-    #[derive(EnumString, Display)]
+#[derive(EnumString, Display, PartialEq, Eq, PartialOrd, Ord, AsRefStr, AsStaticStr)]
 pub enum AreaShape {
     #[strum(to_string = "rect")]
     Rectangle,
@@ -37,10 +36,8 @@ enum_set_type! {
     #[strum(to_string = "default")]
     Default,
 }
-}
 
-enum_set_type! {
-    #[derive(EnumString, Display)]
+#[derive(EnumString, Display, PartialEq, Eq, PartialOrd, Ord, AsRefStr, AsStaticStr)]
 pub enum BoolOrDefault {
     #[strum(to_string = "true")]
     True,
@@ -49,10 +46,8 @@ enum_set_type! {
     #[strum(to_string = "false")]
     False,
 }
-}
 
-enum_set_type! {
-    #[derive(EnumString, Display)]
+#[derive(EnumString, Display, PartialEq, Eq, PartialOrd, Ord, AsRefStr, AsStaticStr)]
 pub enum ButtonType {
     #[strum(to_string = "submit")]
     Submit,
@@ -61,20 +56,16 @@ enum_set_type! {
     #[strum(to_string = "button")]
     Button,
 }
-}
 
-enum_set_type! {
-    #[derive(EnumString, Display)]
+#[derive(EnumString, Display, PartialEq, Eq, PartialOrd, Ord, AsRefStr, AsStaticStr)]
 pub enum CrossOrigin {
     #[strum(to_string = "anonymous")]
     Anonymous,
     #[strum(to_string = "use-credentials")]
     UseCredentials,
 }
-}
 
-enum_set_type! {
-    #[derive(EnumString, Display)]
+#[derive(EnumString, Display, PartialEq, Eq, PartialOrd, Ord, AsRefStr, AsStaticStr)]
 pub enum FormEncodingType {
     #[strum(to_string = "application/x-www-form-urlencoded")]
     UrlEncoded,
@@ -83,20 +74,16 @@ enum_set_type! {
     #[strum(to_string = "text/plain")]
     Text,
 }
-}
 
-enum_set_type! {
-    #[derive(EnumString, Display)]
+#[derive(EnumString, Display, PartialEq, Eq, PartialOrd, Ord, AsRefStr, AsStaticStr)]
 pub enum FormMethod {
     #[strum(to_string = "post")]
     Post,
     #[strum(to_string = "get")]
     Get,
 }
-}
 
-enum_set_type! {
-    #[derive(EnumString, Display)]
+#[derive(EnumString, Display, PartialEq, Eq, PartialOrd, Ord, AsRefStr, AsStaticStr)]
 pub enum ImageDecoding {
     #[strum(to_string = "sync")]
     Sync,
@@ -105,10 +92,8 @@ enum_set_type! {
     #[strum(to_string = "auto")]
     Auto,
 }
-}
 
-enum_set_type! {
-    #[derive(EnumString, Display)]
+#[derive(EnumString, Display, PartialEq, Eq, PartialOrd, Ord, AsRefStr, AsStaticStr)]
 pub enum InputType {
     #[strum(to_string = "button")]
     Button,
@@ -155,10 +140,8 @@ enum_set_type! {
     #[strum(to_string = "week")]
     Week,
 }
-}
 
-enum_set_type! {
-    #[derive(EnumString, Display)]
+#[derive(EnumString, Display, PartialEq, Eq, PartialOrd, Ord, AsRefStr, AsStaticStr)]
 pub enum LinkType {
     #[strum(to_string = "alternate")]
     Alternate,
@@ -205,20 +188,16 @@ enum_set_type! {
     #[strum(to_string = "tag")]
     Tag,
 }
-}
 
-enum_set_type! {
-    #[derive(EnumString, Display)]
+#[derive(EnumString, Display, PartialEq, Eq, PartialOrd, Ord, AsRefStr, AsStaticStr)]
 pub enum OnOff {
     #[strum(to_string = "on")]
     On,
     #[strum(to_string = "off")]
     Off,
 }
-}
 
-enum_set_type! {
-    #[derive(EnumString, Display)]
+#[derive(EnumString, Display, PartialEq, Eq, PartialOrd, Ord, AsRefStr, AsStaticStr)]
 pub enum OrderedListType {
     #[strum(to_string = "a")]
     LowerCaseLetters,
@@ -231,10 +210,8 @@ enum_set_type! {
     #[strum(to_string = "1")]
     Numbers,
 }
-}
 
-enum_set_type! {
-    #[derive(EnumString, Display)]
+#[derive(EnumString, Display, PartialEq, Eq, PartialOrd, Ord, AsRefStr, AsStaticStr)]
 pub enum Preload {
     #[strum(to_string = "none")]
     None,
@@ -243,10 +220,8 @@ enum_set_type! {
     #[strum(to_string = "auto")]
     Auto,
 }
-}
 
-enum_set_type! {
-    #[derive(EnumString, Display)]
+#[derive(EnumString, Display, PartialEq, Eq, PartialOrd, Ord, AsRefStr, AsStaticStr)]
 pub enum ReferrerPolicy {
     #[strum(to_string = "no-referrer")]
     NoReferrer,
@@ -259,10 +234,8 @@ enum_set_type! {
     #[strum(to_string = "unsafe-url")]
     UnsafeUrl,
 }
-}
 
-enum_set_type! {
-    #[derive(EnumString, Display)]
+#[derive(EnumString, Display, PartialEq, Eq, PartialOrd, Ord, AsRefStr, AsStaticStr)]
 pub enum Sandbox {
     #[strum(to_string = "allow-forms")]
     AllowForms,
@@ -287,10 +260,8 @@ enum_set_type! {
     #[strum(to_string = "allow-top-navigation-by-user-navigation")]
     AllowTopNavigationByUserNavigation,
 }
-}
 
-enum_set_type! {
-    #[derive(EnumString, Display)]
+#[derive(EnumString, Display, PartialEq, Eq, PartialOrd, Ord, AsRefStr, AsStaticStr)]
 pub enum TableHeaderScope {
     #[strum(to_string = "row")]
     Row,
@@ -303,20 +274,16 @@ enum_set_type! {
     #[strum(to_string = "auto")]
     Auto,
 }
-}
 
-enum_set_type! {
-    #[derive(EnumString, Display)]
+#[derive(EnumString, Display, PartialEq, Eq, PartialOrd, Ord, AsRefStr, AsStaticStr)]
 pub enum TextDirection {
     #[strum(to_string = "ltr")]
     LeftToRight,
     #[strum(to_string = "rtl")]
     RightToLeft,
 }
-}
 
-enum_set_type! {
-    #[derive(EnumString, Display)]
+#[derive(EnumString, Display, PartialEq, Eq, PartialOrd, Ord, AsRefStr, AsStaticStr)]
 pub enum VideoKind {
     #[strum(to_string = "subtitles")]
     Subtitles,
@@ -329,10 +296,8 @@ enum_set_type! {
     #[strum(to_string = "metadata")]
     Metadata,
 }
-}
 
-enum_set_type! {
-    #[derive(EnumString, Display)]
+#[derive(EnumString, Display, PartialEq, Eq, PartialOrd, Ord, AsRefStr, AsStaticStr)]
 pub enum Wrap {
     #[strum(to_string = "hard")]
     Hard,
@@ -341,4 +306,3 @@ enum_set_type! {
     #[strum(to_string = "off")]
     Off,
 }
-}

typed-html/src/types/spacedlist.rs

@@ -3,10 +3,18 @@ use std::iter::FromIterator;
 use std::ops::{Deref, DerefMut};
 use std::str::FromStr;
 
+/// A space separated list of values.
+///
+/// This type represents a list of non-unique values represented as a string of
+/// values separated by spaces in HTML attributes. This is rarely used; a
+/// [`SpacedSet`][SpacedSet] of unique values is much more common.
+///
+/// [SpacedSet]: struct.SpacedSet.html
 #[derive(Clone, PartialEq, Eq, Hash)]
 pub struct SpacedList<A>(Vec<A>);
 
 impl<A> SpacedList<A> {
+    /// Construct an empty `SpacedList`.
     pub fn new() -> Self {
         SpacedList(Vec::new())
     }

typed-html/src/types/spacedset.rs

@@ -4,10 +4,33 @@ use std::iter::FromIterator;
 use std::ops::{Deref, DerefMut};
 use std::str::FromStr;
 
+/// A space separated set of unique values.
+///
+/// This type represents a set of unique values represented as a string of
+/// values separated by spaces in HTML attributes.
+///
+/// # Examples
+///
+/// ```
+/// # extern crate typed_html;
+/// # use std::convert::From;
+/// use typed_html::types::{Class, SpacedSet};
+///
+/// # fn main() {
+/// let classList: SpacedSet<Class> = "foo bar baz".into();
+/// let classList: SpacedSet<Class> = ["foo", "bar", "baz"].into();
+/// let classList: SpacedSet<Class> = ("foo", "bar", "baz").into();
+///
+/// let classList1: SpacedSet<Class> = "foo bar foo".into();
+/// let classList2: SpacedSet<Class> = "bar foo bar".into();
+/// assert_eq!(classList1, classList2);
+/// # }
+/// ```
 #[derive(Clone, PartialEq, Eq, Hash)]
 pub struct SpacedSet<A: Ord>(BTreeSet<A>);
 
 impl<A: Ord> SpacedSet<A> {
+    /// Construct an empty `SpacedSet`.
     pub fn new() -> Self {
         SpacedSet(BTreeSet::new())
     }
@@ -46,7 +69,7 @@ where
     fn from_str(s: &str) -> Result<Self, Self::Err> {
         let result: Result<Vec<A>, Self::Err> =
             s.split_whitespace().map(|s| FromStr::from_str(s)).collect();
-        result.map(|items| Self::from_iter(items))
+        result.map(Self::from_iter)
     }
 }
 

wasm/src/main.rs

@@ -8,9 +8,7 @@ extern crate typed_html_macros;
 use stdweb::web::{self, Element, IElement, INode};
 use typed_html::dom::{Node, VNode};
 use typed_html::events::Events;
-use typed_html::for_events;
-use typed_html::DOM;
-use typed_html_macros::html;
+use typed_html::{for_events, html, DOM};
 
 fn install_handlers(target: &Element, handlers: &mut Events<DOM>) {
     for_events!(handler in handlers => {