From 276ba3143250ebe26e110d654528d7d5d60fc7c2 Mon Sep 17 00:00:00 2001 From: Bodil Stokke Date: Sat, 17 Nov 2018 20:38:07 +0000 Subject: [PATCH] Documentation++. --- macros/src/lib.rs | 89 +++++++++++++++++++++++++++++++ typed-html/src/dom.rs | 1 - typed-html/src/events.rs | 1 - typed-html/src/lib.rs | 1 + typed-html/src/types/mod.rs | 1 + typed-html/src/types/spacedset.rs | 1 - 6 files changed, 91 insertions(+), 3 deletions(-) diff --git a/macros/src/lib.rs b/macros/src/lib.rs index 8b4cad6..adceca7 100644 --- a/macros/src/lib.rs +++ b/macros/src/lib.rs @@ -18,6 +18,93 @@ mod lexer; mod map; mod parser; +/// Construct a DOM tree. +/// +/// # Syntax +/// +/// This macro largely follows [JSX] syntax, but with some differences: +/// +/// * Text nodes must be quoted, because there's only so much Rust's tokeniser +/// can handle outside string literals. So, instead of `

Hello

`, you +/// need to write `

"Hello"

`. (The parser will throw an error asking you +/// to do this if you forget.) +/// * Element attributes will accept simple Rust expressions, but the parser has +/// its limits, as it's not a full Rust parser. You can use literals, +/// variables, dotted properties and single function or method calls. If you +/// use something the parser isn't currently capable of handling, it will +/// complain. You can put braces or parentheses around the expression if the +/// parser doesn't understand it. You can use any Rust code inside a brace or +/// parenthesis block. +/// +/// # Valid HTML5 +/// +/// The macro will only accept valid HTML5 tags, with no tags or attributes +/// marked experimental or obsolete. If it won't accept something you want it to +/// accept, we can discuss it over a pull request (experimental tags and +/// attributes, in particular, are mostly omitted just for brevity, and you're +/// welcome to implement them). +/// +/// The structure validation is simplistic by necessity, as it defers to the +/// type system: a few elements will have one or more required children, and any +/// element which accepts children will have a restriction on the type of the +/// children, usually a broad group as defined by the HTML spec. Many elements +/// have restrictions on children of children, or require a particular ordering +/// of optional elements, which isn't currently validated. +/// +/// # Attribute Values +/// +/// Brace blocks in the attribute value position should return the expected type +/// for the attribute. The type checker will complain if you return an +/// unsupported type. You can also use literals or a few simple Rust expressions +/// as attribute values (see the Syntax section above). +/// +/// The `html!` macro will add an `.into()` call to the value expression, so +/// that you can use any type that has an `Into` trait defined for the actual +/// attribute type `A`. +/// +/// As a special case, if you use a string literal, the macro will instead use +/// the `FromStr` trait to try and parse the string literal into the expected +/// type. This is extremely useful for eg. CSS classes, letting you type +/// `class="css-class-1 css-class-2"` instead of going to the trouble of +/// constructing a `SpacedSet`. The big caveat for this: currently, the +/// macro is not able to validate the string at compile time, and the conversion +/// will panic at runtime if the string is invalid. +/// +/// ## Example +/// +/// ```no_compile +/// let classList: SpacedSet = ["foo", "bar", "baz"].into(); +/// html!( +///
// parses a string literal +///
// uses From<[&str, &str, &str]> +///
// uses a variable in scope +///
+/// ) +/// ``` +/// +/// # Generated Nodes +/// +/// Brace blocks in the child node position are expected to return an +/// `IntoIterator` of `DOMTree`s. You can return single elements or text nodes, +/// as they both implement `IntoIterator` for themselves. The macro will consume +/// this iterator at runtime and insert the generated nodes as children in the +/// expected position. +/// +/// ## Example +/// +/// ```no_compile +/// html!( +///
    +/// { (1..=5).map(|i| html!( +///
  • { text!("{}", i) }
    • +/// )) } +///
+/// ) +/// ``` +/// +/// [JSX]: https://reactjs.org/docs/introducing-jsx.html #[proc_macro] pub fn html(input: TokenStream) -> TokenStream { let stream = lexer::unroll_stream(input, false); @@ -31,6 +118,8 @@ pub fn html(input: TokenStream) -> TokenStream { } } +/// This macro is used by `typed_html` internally to generate types and +/// implementations for HTML elements. #[proc_macro] pub fn declare_elements(input: TokenStream) -> TokenStream { let stream = lexer::keywordise(lexer::unroll_stream(input, true)); diff --git a/typed-html/src/dom.rs b/typed-html/src/dom.rs index 8bf74ec..c452e96 100644 --- a/typed-html/src/dom.rs +++ b/typed-html/src/dom.rs @@ -14,7 +14,6 @@ use htmlescape::encode_minimal; /// /// ``` /// # #![feature(proc_macro_hygiene)] -/// # extern crate typed_html; /// # use typed_html::html; /// # use typed_html::dom::DOMTree; /// # fn main() { diff --git a/typed-html/src/events.rs b/typed-html/src/events.rs index d11bfed..77cfb80 100644 --- a/typed-html/src/events.rs +++ b/typed-html/src/events.rs @@ -31,7 +31,6 @@ macro_rules! declare_events { /// /// ``` /// # #![feature(proc_macro_hygiene)] - /// # extern crate typed_html; /// # use typed_html::{html, for_events}; /// # use typed_html::dom::{DOMTree, VNode}; /// # fn main() { diff --git a/typed-html/src/lib.rs b/typed-html/src/lib.rs index ca76314..6c92cc5 100644 --- a/typed-html/src/lib.rs +++ b/typed-html/src/lib.rs @@ -11,6 +11,7 @@ extern crate stdweb; extern crate strum; extern crate typed_html_macros; +#[doc(inline)] pub use typed_html_macros::html; pub mod dom; diff --git a/typed-html/src/types/mod.rs b/typed-html/src/types/mod.rs index 3fa706c..41fa1ae 100644 --- a/typed-html/src/types/mod.rs +++ b/typed-html/src/types/mod.rs @@ -18,6 +18,7 @@ pub use http::Uri; pub use language_tags::LanguageTag; pub use mime::Mime; +// FIXME these all need validating types pub type CharacterEncoding = String; pub type Datetime = String; pub type FeaturePolicy = String; diff --git a/typed-html/src/types/spacedset.rs b/typed-html/src/types/spacedset.rs index e5cd578..3741634 100644 --- a/typed-html/src/types/spacedset.rs +++ b/typed-html/src/types/spacedset.rs @@ -12,7 +12,6 @@ use std::str::FromStr; /// # Examples /// /// ``` -/// # extern crate typed_html; /// # use std::convert::From; /// use typed_html::types::{Class, SpacedSet}; ///