Auto merge of #10366 - emilio:style-docs, r=SimonSapin

style: Improve style::selector_matching documentation

r? @mbrubeck

<!-- Reviewable:start -->
---
This change is [<img src="https://reviewable.io/review_button.svg" height="35" align="absmiddle" alt="Reviewable"/>](https://reviewable.io/reviews/servo/servo/10366)
<!-- Reviewable:end -->

1 files changed, 47 insertions, 14 deletions

diff --git a/components/style/selector_matching.rs b/components/style/selector_matching.rs
index bb063c805e3..d210f888e39 100644
--- a/components/style/selector_matching.rs
+++ b/components/style/selector_matching.rs
@@ -83,27 +83,47 @@ lazy_static! {
     };
 }
 
+/// This structure holds all the selectors and device characteristics
+/// for a given document. The selectors are converted into `Rule`s
+/// (defined in rust-selectors), and introduced in a `SelectorMap`
+/// depending on the pseudo-element (see `PerPseudoElementSelectorMap`),
+/// stylesheet origin (see `PerOriginSelectorMap`), and priority
+/// (see the `normal` and `important` fields in `PerOriginSelectorMap`).
+///
+/// This structure is effectively created once per pipeline, in the
+/// LayoutThread corresponding to that pipeline.
+///
+/// The stylist is parameterized on `SelectorImplExt`, a trait that extends
+/// `selectors::parser::SelectorImpl`, and that allows to customise what
+/// pseudo-classes and pseudo-elements are parsed. This is actually either
+/// `ServoSelectorImpl`, the implementation used by Servo's layout system in
+/// regular builds, or `GeckoSelectorImpl`, the implementation used in the
+/// geckolib port.
 #[derive(HeapSizeOf)]
 pub struct Stylist<Impl: SelectorImplExt> {
-    // Device that the stylist is currently evaluating against.
+    /// Device that the stylist is currently evaluating against.
     pub device: Device,
 
-    // Viewport constraints based on the current device.
+    /// Viewport constraints based on the current device.
     viewport_constraints: Option<ViewportConstraints>,
 
-    // If true, the quirks-mode stylesheet is applied.
+    /// If true, the quirks-mode stylesheet is applied.
     quirks_mode: bool,
 
-    // If true, the device has changed, and the stylist needs to be updated.
+    /// If true, the device has changed, and the stylist needs to be updated.
     is_device_dirty: bool,
 
-    // The current selector maps, after evaluating media
-    // rules against the current device.
+    /// The current selector maps, after evaluating media
+    /// rules against the current device.
     element_map: PerPseudoElementSelectorMap<Impl>,
-    pseudos_map: HashMap<Impl::PseudoElement, PerPseudoElementSelectorMap<Impl>, BuildHasherDefault<::fnv::FnvHasher>>,
+    /// The selector maps corresponding to a given pseudo-element
+    /// (depending on the implementation)
+    pseudos_map: HashMap<Impl::PseudoElement,
+                         PerPseudoElementSelectorMap<Impl>,
+                         BuildHasherDefault<::fnv::FnvHasher>>,
     rules_source_order: usize,
 
-    // Selector dependencies used to compute restyle hints.
+    /// Selector dependencies used to compute restyle hints.
     state_deps: DependencySet<Impl>,
 }
 
@@ -137,6 +157,7 @@ impl<Impl: SelectorImplExt> Stylist<Impl> {
         if !(self.is_device_dirty || stylesheets_changed) {
             return false;
         }
+
         self.element_map = PerPseudoElementSelectorMap::new();
         self.pseudos_map = HashMap::with_hasher(Default::default());
         self.rules_source_order = 0;
@@ -171,7 +192,7 @@ impl<Impl: SelectorImplExt> Stylist<Impl> {
         // them into the SelectorMap of that priority.
         macro_rules! append(
             ($style_rule: ident, $priority: ident) => {
-                if $style_rule.declarations.$priority.len() > 0 {
+                if !$style_rule.declarations.$priority.is_empty() {
                     for selector in &$style_rule.selectors {
                         let map = if let Some(ref pseudo) = selector.pseudo_element {
                             self.pseudos_map.entry(pseudo.clone())
@@ -243,12 +264,13 @@ impl<Impl: SelectorImplExt> Stylist<Impl> {
         self.quirks_mode = enabled;
     }
 
-    /// Returns the applicable CSS declarations for the given element. This corresponds to
-    /// `ElementRuleCollector` in WebKit.
+    /// Returns the applicable CSS declarations for the given element.
+    /// This corresponds to `ElementRuleCollector` in WebKit.
     ///
-    /// The returned boolean indicates whether the style is *shareable*; that is, whether the
-    /// matched selectors are simple enough to allow the matching logic to be reduced to the logic
-    /// in `css::matching::PrivateMatchMethods::candidate_element_allows_for_style_sharing`.
+    /// The returned boolean indicates whether the style is *shareable*;
+    /// that is, whether the matched selectors are simple enough to allow the
+    /// matching logic to be reduced to the logic in
+    /// `css::matching::PrivateMatchMethods::candidate_element_allows_for_style_sharing`.
     pub fn push_applicable_declarations<E, V>(
                                         &self,
                                         element: &E,
@@ -333,14 +355,20 @@ impl<Impl: SelectorImplExt> Stylist<Impl> {
         shareable
     }
 
+    #[inline]
     pub fn is_device_dirty(&self) -> bool {
         self.is_device_dirty
     }
 }
 
+/// Map that contains the CSS rules for a given origin.
 #[derive(HeapSizeOf)]
 struct PerOriginSelectorMap<Impl: SelectorImpl> {
+    /// Rules that contains at least one property declararion with
+    /// normal importance.
     normal: SelectorMap<Vec<PropertyDeclaration>, Impl>,
+    /// Rules that contains at least one property declararion with
+    /// !important.
     important: SelectorMap<Vec<PropertyDeclaration>, Impl>,
 }
 
@@ -354,10 +382,15 @@ impl<Impl: SelectorImpl> PerOriginSelectorMap<Impl> {
     }
 }
 
+/// Map that contains the CSS rules for a specific PseudoElement
+/// (or lack of PseudoElement).
 #[derive(HeapSizeOf)]
 struct PerPseudoElementSelectorMap<Impl: SelectorImpl> {
+    /// Rules from user agent stylesheets
     user_agent: PerOriginSelectorMap<Impl>,
+    /// Rules from author stylesheets
     author: PerOriginSelectorMap<Impl>,
+    /// Rules from user stylesheets
     user: PerOriginSelectorMap<Impl>,
 }