Document the relationship between the core node and element types

scraper/src/lib.rs

@@ -11,6 +11,43 @@
     variant_size_differences
 )]
 
+//! # The core types
+//!
+//! Parsing an input produces an [`Html`] document that owns a tree of
+//! [`Node`]s. Every node is one variant of the [`Node`] enum, for example
+//! [`Node::Text`] for text and [`Node::Element`] for an element. The data that
+//! belongs to an element node, its name and its attributes, is held in a
+//! [`node::Element`](crate::node::Element).
+//!
+//! Running a [`Selector`] over a document does not hand back bare [`Node`]s.
+//! It yields [`ElementRef`]s, each one a handle to an element node that also
+//! knows where it sits in the tree. From an [`ElementRef`] you can reach the
+//! element data with [`ElementRef::value`], read the text under it with
+//! [`ElementRef::text`], or select further into its descendants. Because an
+//! [`ElementRef`] also dereferences to an `ego_tree::NodeRef`, the tree
+//! navigation methods (parent, children, siblings) are available on it too.
+//!
+//! The re-exported [`Element`] trait is a different thing from
+//! [`node::Element`](crate::node::Element). The trait comes from the
+//! `selectors` crate and is what lets an [`ElementRef`] be matched against a
+//! CSS selector. Most code never needs to name it directly.
+//!
+//! ```
+//! use scraper::{Html, Selector};
+//!
+//! let document = Html::parse_fragment(r#"<ul><li id="a">one</li><li>two</li></ul>"#);
+//! let selector = Selector::parse("li").unwrap();
+//!
+//! for element in document.select(&selector) {
+//!     // The element data: its tag name and attributes.
+//!     let name = element.value().name();
+//!     let id = element.value().id();
+//!     // The text nodes below this element, concatenated.
+//!     let text = element.text().collect::<String>();
+//!     println!("{name} id={id:?} text={text:?}");
+//! }
+//! ```
+
 #[macro_use]
 extern crate html5ever;
 

scraper/src/node.rs

@@ -217,7 +217,13 @@ pub type Attributes = indexmap::IndexMap<QualName, StrTendril>;
 #[cfg(not(feature = "deterministic"))]
 pub type Attributes = Vec<(QualName, StrTendril)>;
 
-/// An HTML element.
+/// The name and attributes of an HTML element.
+///
+/// This is the data stored in a [`Node::Element`] node. It is distinct from the
+/// [`Element`](selectors::Element) trait re-exported at the crate root, which is
+/// implemented by [`ElementRef`](crate::ElementRef) for CSS selector matching.
+/// To get one from a selected element, call
+/// [`ElementRef::value`](crate::ElementRef::value).
 #[derive(Clone, PartialEq, Eq)]
 pub struct Element {
     /// The element name.