Add doc comments for cosmetic filter structs/methods

src/cosmetic_filter_cache.rs

@@ -12,6 +12,19 @@ lazy_static! {
     static ref PUBLIC_SUFFIXES: psl::List = psl::List::new();
 }
 
+/// Contains cosmetic filter information intended to be injected into a particular hostname.
+///
+/// `hide_selectors` is a set of any CSS selector on the page that should be hidden, i.e. styled as
+/// `{ display: none !important; }`.
+///
+/// `style_selectors` is a map of CSS selectors on the page to respective non-hide style rules,
+/// i.e. any required styles other than `display: none`.
+///
+/// `exceptions` is a set of any class or id CSS selectors that should not have generic rules
+/// applied. In practice, these should be passed to `class_id_stylesheet` and not used otherwise.
+///
+/// `injected_script` is the Javascript code for any scriptlets that should be injected into the
+/// page.
 #[derive(Debug, PartialEq, Eq, Deserialize, Serialize)]
 pub struct HostnameSpecificResources {
     pub hide_selectors: HashSet<String>,

src/engine.rs

@@ -217,10 +217,18 @@ impl Engine {
 
     // Cosmetic filter functionality
 
-    pub fn class_id_stylesheet(&self, classes: &[String], ids: &[String], exceptions: HashSet<String>) -> Option<String> {
-        self.cosmetic_cache.class_id_stylesheet(classes, ids, &exceptions)
-    }
-
+    /// If any of the provided CSS classes or ids could cause a certain generic CSS hide rule
+    /// (i.e. `{ display: none !important; }`) to be required, this method will return a stylesheet
+    /// including it, providing that the corresponding rule does not have an exception.
+    ///
+    /// `exceptions` should be passed directly from `HostnameSpecificResources`.
+    pub fn class_id_stylesheet(&self, classes: &[String], ids: &[String], exceptions: &HashSet<String>) -> Option<String> {
+        self.cosmetic_cache.class_id_stylesheet(classes, ids, exceptions)
+    }
+
+    /// Returns a set of cosmetic filter resources required for a particular hostname. Once this
+    /// has been called, all CSS ids and classes on a page should be passed to
+    /// `class_id_stylesheet` to obtain any stylesheets consisting of generic rules.
     pub fn hostname_cosmetic_resources(&self, hostname: &str) -> HostnameSpecificResources {
         self.cosmetic_cache.hostname_cosmetic_resources(hostname)
     }