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::{dom::DOMTree, html, text};
-use typed_html_macros::html;
 
-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.
+    /// Construct a new class name from a string.
-    //
+    ///
-    // Returns `None` if the provided string is invalid.
+    /// 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.
+    /// Construct a new class name from a string.
-    //
+    ///
-    // Panics if the provided string is invalid.
+    /// 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.
+    /// Construct a new ID from a string.
-    //
+    ///
-    // Returns `None` if the provided string is invalid.
+    /// 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.
+    /// Construct a new ID from a string.
-    //
+    ///
-    // Panics if the provided string is invalid.
+    /// 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,9 +25,8 @@ pub type Integrity = String;
 pub type Nonce = String;
 pub type Target = String;
 
-enum_set_type! {
+#[derive(EnumString, Display, PartialEq, Eq, PartialOrd, Ord, AsRefStr, AsStaticStr)]
-    #[derive(EnumString, Display)]
+pub enum AreaShape {
-    pub enum AreaShape {
     #[strum(to_string = "rect")]
     Rectangle,
     #[strum(to_string = "circle")]
@@ -36,80 +35,66 @@ enum_set_type! {
     Polygon,
     #[strum(to_string = "default")]
     Default,
-    }
 }
 
-enum_set_type! {
+#[derive(EnumString, Display, PartialEq, Eq, PartialOrd, Ord, AsRefStr, AsStaticStr)]
-    #[derive(EnumString, Display)]
+pub enum BoolOrDefault {
-    pub enum BoolOrDefault {
     #[strum(to_string = "true")]
     True,
     #[strum(to_string = "default")]
     Default,
     #[strum(to_string = "false")]
     False,
-    }
 }
 
-enum_set_type! {
+#[derive(EnumString, Display, PartialEq, Eq, PartialOrd, Ord, AsRefStr, AsStaticStr)]
-    #[derive(EnumString, Display)]
+pub enum ButtonType {
-    pub enum ButtonType {
     #[strum(to_string = "submit")]
     Submit,
     #[strum(to_string = "reset")]
     Reset,
     #[strum(to_string = "button")]
     Button,
-    }
 }
 
-enum_set_type! {
+#[derive(EnumString, Display, PartialEq, Eq, PartialOrd, Ord, AsRefStr, AsStaticStr)]
-    #[derive(EnumString, Display)]
+pub enum CrossOrigin {
-    pub enum CrossOrigin {
     #[strum(to_string = "anonymous")]
     Anonymous,
     #[strum(to_string = "use-credentials")]
     UseCredentials,
-    }
 }
 
-enum_set_type! {
+#[derive(EnumString, Display, PartialEq, Eq, PartialOrd, Ord, AsRefStr, AsStaticStr)]
-    #[derive(EnumString, Display)]
+pub enum FormEncodingType {
-    pub enum FormEncodingType {
     #[strum(to_string = "application/x-www-form-urlencoded")]
     UrlEncoded,
     #[strum(to_string = "multipart/form-data")]
     FormData,
     #[strum(to_string = "text/plain")]
     Text,
-    }
 }
 
-enum_set_type! {
+#[derive(EnumString, Display, PartialEq, Eq, PartialOrd, Ord, AsRefStr, AsStaticStr)]
-    #[derive(EnumString, Display)]
+pub enum FormMethod {
-    pub enum FormMethod {
     #[strum(to_string = "post")]
     Post,
     #[strum(to_string = "get")]
     Get,
-    }
 }
 
-enum_set_type! {
+#[derive(EnumString, Display, PartialEq, Eq, PartialOrd, Ord, AsRefStr, AsStaticStr)]
-    #[derive(EnumString, Display)]
+pub enum ImageDecoding {
-    pub enum ImageDecoding {
     #[strum(to_string = "sync")]
     Sync,
     #[strum(to_string = "async")]
     Async,
     #[strum(to_string = "auto")]
     Auto,
-    }
 }
 
-enum_set_type! {
+#[derive(EnumString, Display, PartialEq, Eq, PartialOrd, Ord, AsRefStr, AsStaticStr)]
-    #[derive(EnumString, Display)]
+pub enum InputType {
-    pub enum InputType {
     #[strum(to_string = "button")]
     Button,
     #[strum(to_string = "checkbox")]
@@ -154,12 +139,10 @@ enum_set_type! {
     Url,
     #[strum(to_string = "week")]
     Week,
-    }
 }
 
-enum_set_type! {
+#[derive(EnumString, Display, PartialEq, Eq, PartialOrd, Ord, AsRefStr, AsStaticStr)]
-    #[derive(EnumString, Display)]
+pub enum LinkType {
-    pub enum LinkType {
     #[strum(to_string = "alternate")]
     Alternate,
     #[strum(to_string = "author")]
@@ -204,22 +187,18 @@ enum_set_type! {
     StyleSheet,
     #[strum(to_string = "tag")]
     Tag,
-    }
 }
 
-enum_set_type! {
+#[derive(EnumString, Display, PartialEq, Eq, PartialOrd, Ord, AsRefStr, AsStaticStr)]
-    #[derive(EnumString, Display)]
+pub enum OnOff {
-    pub enum OnOff {
     #[strum(to_string = "on")]
     On,
     #[strum(to_string = "off")]
     Off,
-    }
 }
 
-enum_set_type! {
+#[derive(EnumString, Display, PartialEq, Eq, PartialOrd, Ord, AsRefStr, AsStaticStr)]
-    #[derive(EnumString, Display)]
+pub enum OrderedListType {
-    pub enum OrderedListType {
     #[strum(to_string = "a")]
     LowerCaseLetters,
     #[strum(to_string = "A")]
@@ -230,24 +209,20 @@ enum_set_type! {
     UpperCaseRomanNumerals,
     #[strum(to_string = "1")]
     Numbers,
-    }
 }
 
-enum_set_type! {
+#[derive(EnumString, Display, PartialEq, Eq, PartialOrd, Ord, AsRefStr, AsStaticStr)]
-    #[derive(EnumString, Display)]
+pub enum Preload {
-    pub enum Preload {
     #[strum(to_string = "none")]
     None,
     #[strum(to_string = "metadata")]
     Metadata,
     #[strum(to_string = "auto")]
     Auto,
-    }
 }
 
-enum_set_type! {
+#[derive(EnumString, Display, PartialEq, Eq, PartialOrd, Ord, AsRefStr, AsStaticStr)]
-    #[derive(EnumString, Display)]
+pub enum ReferrerPolicy {
-    pub enum ReferrerPolicy {
     #[strum(to_string = "no-referrer")]
     NoReferrer,
     #[strum(to_string = "no-referrer-when-downgrade")]
@@ -258,12 +233,10 @@ enum_set_type! {
     OriginWhenCrossOrigin,
     #[strum(to_string = "unsafe-url")]
     UnsafeUrl,
-    }
 }
 
-enum_set_type! {
+#[derive(EnumString, Display, PartialEq, Eq, PartialOrd, Ord, AsRefStr, AsStaticStr)]
-    #[derive(EnumString, Display)]
+pub enum Sandbox {
-    pub enum Sandbox {
     #[strum(to_string = "allow-forms")]
     AllowForms,
     #[strum(to_string = "allow-modals")]
@@ -286,12 +259,10 @@ enum_set_type! {
     AllowTopNavigation,
     #[strum(to_string = "allow-top-navigation-by-user-navigation")]
     AllowTopNavigationByUserNavigation,
-    }
 }
 
-enum_set_type! {
+#[derive(EnumString, Display, PartialEq, Eq, PartialOrd, Ord, AsRefStr, AsStaticStr)]
-    #[derive(EnumString, Display)]
+pub enum TableHeaderScope {
-    pub enum TableHeaderScope {
     #[strum(to_string = "row")]
     Row,
     #[strum(to_string = "col")]
@@ -302,22 +273,18 @@ enum_set_type! {
     ColGroup,
     #[strum(to_string = "auto")]
     Auto,
-    }
 }
 
-enum_set_type! {
+#[derive(EnumString, Display, PartialEq, Eq, PartialOrd, Ord, AsRefStr, AsStaticStr)]
-    #[derive(EnumString, Display)]
+pub enum TextDirection {
-    pub enum TextDirection {
     #[strum(to_string = "ltr")]
     LeftToRight,
     #[strum(to_string = "rtl")]
     RightToLeft,
-    }
 }
 
-enum_set_type! {
+#[derive(EnumString, Display, PartialEq, Eq, PartialOrd, Ord, AsRefStr, AsStaticStr)]
-    #[derive(EnumString, Display)]
+pub enum VideoKind {
-    pub enum VideoKind {
     #[strum(to_string = "subtitles")]
     Subtitles,
     #[strum(to_string = "captions")]
@@ -328,17 +295,14 @@ enum_set_type! {
     Chapters,
     #[strum(to_string = "metadata")]
     Metadata,
-    }
 }
 
-enum_set_type! {
+#[derive(EnumString, Display, PartialEq, Eq, PartialOrd, Ord, AsRefStr, AsStaticStr)]
-    #[derive(EnumString, Display)]
+pub enum Wrap {
-    pub enum Wrap {
     #[strum(to_string = "hard")]
     Hard,
     #[strum(to_string = "soft")]
     Soft,
     #[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::{for_events, html, DOM};
-use typed_html::DOM;
-use typed_html_macros::html;
 
 fn install_handlers(target: &Element, handlers: &mut Events<DOM>) {
     for_events!(handler in handlers => {