Document the relationship between the core node and element types - #323
Document the relationship between the core node and element types#323ChrisJr404 wants to merge 2 commits into
Conversation
| pub type Attributes = Vec<(QualName, StrTendril)>; | ||
|
|
||
| /// An HTML element. | ||
| /// The name and attributes of an HTML element. |
There was a problem hiding this comment.
While technically correct, this is still the representation of "an HTML element" we use in this crate, not a deliberate subset of name and attributes, so "An HTML element" seems more appropriate conceptually IMO.
| /// To get one from a selected element, call | ||
| /// [`ElementRef::value`](crate::ElementRef::value). |
There was a problem hiding this comment.
| /// To get one from a selected element, call | |
| /// [`ElementRef::value`](crate::ElementRef::value). | |
| /// To access the underlying element of a selected element, call | |
| /// [`ElementRef::value`](crate::ElementRef::value). |
| //! // 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. |
There was a problem hiding this comment.
I think it is useful to highlight that this matches all descendant text nodes, e.g. by using <li>two <em>three</em></li> as the second list item.
|
|
||
| //! # The core types | ||
| //! | ||
| //! Parsing an input produces an [`Html`] document that owns a tree of |
There was a problem hiding this comment.
| //! Parsing an input produces an [`Html`] document that owns a tree of | |
| //! Parsing produces an [`Html`] document that owns a tree of |
"input" does not really add anything.
| //! 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 |
There was a problem hiding this comment.
Please try to avoid specifying the data "which makes up an element" as this could change in the future. Prefer a style that names examples if you want to keep them as hints, e.g. "that belongs to an element node, like its attributes, is held in".
| //! [`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 |
There was a problem hiding this comment.
Maybe expand this to explicitly say that CSS selectors can only match elements?
| //! let selector = Selector::parse("li").unwrap(); | ||
| //! | ||
| //! for element in document.select(&selector) { | ||
| //! // The element data: its tag name and attributes. |
There was a problem hiding this comment.
Also note that the preferred/short-hand way to access attributes, is ElementRef::attr which might warrant mentioning it here.
| //! 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. |
There was a problem hiding this comment.
While true, the most common usage I see is for convenience methods like parent_element and so on provided by the trait impl which I think is also why we have the re-export.
|
Thanks for the detailed read. Pushed a revision:
|
2 participants
Closes #210. Adds a short overview in the crate docs explaining how Html, Node, node::Element, ElementRef and the re-exported Element trait relate and how you move between them, with a runnable example, and clarifies the node::Element doc so it is not confused with the selectors Element trait.