Auto merge of #370 - Ygg01:docs_qual_name, r=jdm

Extended examples in API docs for QualName

This PR adds documentation for `QualName` as well as some doc tests for it relating to #367 . @kornelski is this what you had in mind?

This PR is a minor change (since no API was changed other than the docs).

Comments and suggestions welcome.

Author: bors-servo

markup5ever/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "markup5ever"
-version = "0.7.6"
+version = "0.7.7"
 authors = [ "The html5ever Project Developers" ]
 license = "MIT / Apache-2.0"
 repository = "https://github.com/servo/html5ever"

markup5ever/interface/mod.rs

@@ -102,8 +102,9 @@ pub mod tree_builder;
 /// at the same time. However if we declare a namespace we could instead say:
 ///
 /// ```text
+/// 
 /// // Furniture XML
-/// <furn:table>
+/// <furn:table xmlns:furn="https://furniture.rs">
 ///   <furn:name>African Coffee Table</furn:name>
 ///   <furn:width>80</furn:width>
 ///   <furn:length>120</furn:length>
@@ -119,21 +120,171 @@ pub mod tree_builder;
 ///    |    |
 ///    |    +- local name
 ///    |
-///  prefix (when resolved gives namespace_url)
+///  prefix (when resolved gives namespace_url `https://furniture.rs`)
 /// ```
+/// 
+/// NOTE: `Prefix`, `LocalName` and `Prefix` are all derivative of 
+/// `string_cache::atom::Atom` and `Atom` implements `Deref<str>`.
+/// 
 #[derive(PartialEq, Eq, PartialOrd, Ord, Hash, Debug, Clone)]
 #[cfg_attr(feature = "heap_size", derive(HeapSizeOf))]
 pub struct QualName {
-    /// The namespace before resolution (e.g. `furn` in `<furn:table>` above).
+    /// The prefix of qualified (e.g. `furn` in `<furn:table>` above).
+    /// Optional (since some namespaces can be empty or inferred), and
+    /// only useful for namespace resolution (since different prefix 
+    /// can still resolve to same namespace)
+    ///
+    /// ```
+    ///
+    /// # fn main() {
+    /// use markup5ever::{QualName, Namespace, LocalName, Prefix};
+    /// 
+    /// let qual = QualName::new(
+    ///     Some(Prefix::from("furn")),
+    ///     Namespace::from("https://furniture.rs"),
+    ///     LocalName::from("table"),
+    /// );
+    /// 
+    /// assert_eq!("furn", &qual.prefix.unwrap());
+    /// 
+    /// # }
+    /// ```
     pub prefix: Option<Prefix>,
-    /// The namespace after resolution.
+    /// The namespace after resolution (e.g. `https://furniture.rs` in example above).
+    /// 
+    /// ```
+    /// # use markup5ever::{QualName, Namespace, LocalName, Prefix};
+    /// 
+    /// # fn main() {
+    /// # let qual = QualName::new(
+    /// #    Some(Prefix::from("furn")),
+    /// #    Namespace::from("https://furniture.rs"),
+    /// #    LocalName::from("table"),
+    /// # );
+    /// 
+    /// assert_eq!("https://furniture.rs", &qual.ns);
+    /// # }
+    /// ```
+    /// 
+    /// When matching namespaces used by HTML we can use `ns!` macro. 
+    /// Although keep in mind that ns! macro only works with namespaces
+    /// that are present in HTML spec (like `html`, `xmlns`, `svg`, etc.).
+    /// 
+    /// ```
+    /// #[macro_use] extern crate markup5ever;
+    /// 
+    /// # use markup5ever::{QualName, Namespace, LocalName, Prefix};
+    /// 
+    /// let html_table = QualName::new(
+    ///    None,
+    ///    ns!(html),
+    ///    LocalName::from("table"),
+    /// );
+    /// 
+    /// assert!(
+    ///   match html_table.ns {
+    ///     ns!(html) => true,
+    ///     _ => false,
+    ///   }
+    /// );
+    /// 
+    /// ```
     pub ns: Namespace,
     /// The local name (e.g. `table` in `<furn:table>` above).
+    /// 
+    /// ```
+    /// # use markup5ever::{QualName, Namespace, LocalName, Prefix};
+    /// 
+    /// # fn main() {
+    /// # let qual = QualName::new(
+    /// #    Some(Prefix::from("furn")),
+    /// #    Namespace::from("https://furniture.rs"),
+    /// #    LocalName::from("table"),
+    /// # );
+    /// 
+    /// assert_eq!("table", &qual.local);
+    /// # }
+    /// ```
+    /// When matching local name we can also use the `local_name!` macro:
+    /// 
+    /// ```
+    /// #[macro_use] extern crate markup5ever;
+    /// 
+    /// # use markup5ever::{QualName, Namespace, LocalName, Prefix};
+    /// 
+    /// # let qual = QualName::new(
+    /// #    Some(Prefix::from("furn")),
+    /// #    Namespace::from("https://furniture.rs"),
+    /// #    LocalName::from("table"),
+    /// # );
+    /// 
+    /// // Initialize qual to furniture example 
+    /// 
+    /// assert!(
+    ///   match qual.local {
+    ///     local_name!("table") => true,
+    ///     _ => false,
+    ///   }
+    /// );
+    /// 
+    /// ```
     pub local: LocalName,
 }
 
 impl QualName {
-    /// Simple constructor function.
+    /// Basic constructor function.
+    ///
+    /// First let's try it for the following example where `QualName` 
+    /// is defined as:
+    /// ```text
+    /// <furn:table> <!-- namespace url is https://furniture.rs -->
+    /// ```
+    ///
+    /// Given this definition, we can define `QualName` using strings.
+    /// 
+    /// ```
+    /// use markup5ever::{QualName, Namespace, LocalName, Prefix};
+    /// 
+    /// # fn main() {
+    /// let qual_name = QualName::new(
+    ///     Some(Prefix::from("furn")),
+    ///     Namespace::from("https://furniture.rs"),
+    ///     LocalName::from("table"),
+    /// );
+    /// # }
+    /// ```
+    ///
+    /// If we were instead to construct this element instead:
+    /// 
+    /// ```text
+    /// 
+    /// <table>
+    ///  ^^^^^---- no prefix and thus default html namespace
+    /// 
+    /// ```
+    /// 
+    /// Or could define it using macros, like so:
+    /// 
+    /// ```
+    /// #[macro_use] extern crate markup5ever;
+    /// use markup5ever::{QualName, Namespace, LocalName, Prefix};
+    /// 
+    /// # fn main() {
+    /// let qual_name = QualName::new(
+    ///     None,
+    ///     ns!(html),
+    ///     local_name!("table")
+    /// );
+    /// # }
+    /// ```
+    /// 
+    /// Let's analyse the above example. 
+    /// Since we have no prefix its value is None. Second we have html namespace. 
+    /// In html5ever html namespaces are supported out of the box, 
+    /// we can write `ns!(html)` instead of typing `Namespace::from("http://www.w3.org/1999/xhtml")`.
+    /// Local name is also one of the HTML elements local names, so can 
+    /// use `local_name!("table")` macro.
+    /// 
     #[inline]
     pub fn new(prefix: Option<Prefix>, ns: Namespace, local: LocalName) -> QualName {
         QualName {
@@ -144,6 +295,25 @@ impl QualName {
     }
 
     /// Take a reference of `self` as an `ExpandedName`, dropping the unresolved prefix.
+    /// 
+    /// In XML and HTML prefixes are only used to extract the relevant namespace URI.
+    /// Expanded name only contains resolved namespace and tag name, which are only
+    /// relevant parts of an XML or HTML tag and attribute name respectively.
+    /// 
+    /// In lieu of our XML Namespace example
+    /// 
+    /// ```text
+    /// <furn:table> <!-- namespace url is https://furniture.rs -->
+    /// ```
+    /// For it the expanded name would become roughly equivalent to:
+    /// 
+    /// ```text
+    /// ExpandedName {
+    ///    ns: "https://furniture.rs",
+    ///    local: "table",
+    /// }
+    /// ```
+    /// 
     #[inline]
     pub fn expanded(&self) -> ExpandedName {
         ExpandedName {