Issue 4167 - getSelectorsForDomain criteria + keys

lib/elemHide.js

 /*
  * This file is part of Adblock Plus <https://adblockplus.org/>,
  * Copyright (C) 2006-2016 Eyeo GmbH
  *
  * Adblock Plus is free software: you can redistribute it and/or modify
  * it under the terms of the GNU General Public License version 3 as
  * published by the Free Software Foundation.
  *
  * Adblock Plus is distributed in the hope that it will be useful,
  * but WITHOUT ANY WARRANTY; without even the implied warranty of
@@ skipping 310 matching lines @@
       let selectors = this.getUnconditionalSelectors();
       unconditionalFilterKeys = [];
       for (let selector of selectors)
         unconditionalFilterKeys.push(filterKeysBySelector[selector][0]);
     }
     return unconditionalFilterKeys.slice();
   },
 
 
   /**
-   * Constant used by getSelectorsForDomain's when matching all selectors.

[Wladimir Palant, 2016/09/27 13:08:38]

Nit: why "'s"?

How about: Constant used by getSelectorsForDomain to return all selectors
applying on a particular hostname.

[kzar, 2016/09/27 13:53:06]

No idea, I guess it's a typo that I missed and then copy-pasted... Done.

+   * Constant used by getSelectorsForDomain to return all selectors applying to
+   * a particular hostname.
    */
   ALL_MATCHING: 0,
 
   /**
-   * Constant used by getSelectorsForDomain's when not matching unconditional
-   * selectors.

[Wladimir Palant, 2016/09/27 13:08:38]

How about: Constant used by getSelectorsForDomain to exclude filters matching on
all websites without exception.

[kzar, 2016/09/27 13:53:06]

Done.

+   * Constant used by getSelectorsForDomain to exclude selectors which apply to
+   * all websites without exception.
    */
   NO_UNCONDITIONAL: 1,
 
   /**
-   * Constant used by getSelectorsForDomain's when only matching specific
-   * selectors.

[Wladimir Palant, 2016/09/27 13:08:38]

Nit: Just realized, "specific selectors" makes no sense.

How about: Constant used by getSelectorsForDomain to return only selectors for
filters which specifically match the given host name.

[kzar, 2016/09/27 13:53:06]

Done.

+   * Constant used by getSelectorsForDomain to return only selectors for filters
+   * which specifically match the given host name.
    */
   SPECIFIC_ONLY: 2,
 
   /**
    * Determines from the current filter list which selectors should be applied
    * on a particular host name. Optionally returns the corresponding filter
    * keys.
    * @param {String} domain
    * @param {Number} [criteria]
-   * One of the following:

[Wladimir Palant, 2016/09/27 13:08:38]

Nit: Please indent parameter and return value descriptions - the blocks here
should be clearly visible.

[kzar, 2016/09/27 13:53:06]

Done.

-   *  ElemHide.ALL_MATCHING - Returns all matching selectors for the host name.
-   *  ElemHide.NO_UNCONDITIONAL - Returns all matching selectors except those
-   *                              which match all host names unconditionally.
-   *  ElemHide.SPECIFIC_ONLY - Returns only selectors for filters which
-   *                           specifically match the given host name.

[Wladimir Palant, 2016/09/27 13:08:38]

Please don't document these constants twice, just reference them here.

[kzar, 2016/09/27 13:53:06]

Done.

+   *   One of the following: ElemHide.ALL_MATCHING, ElemHide.NO_UNCONDITIONAL or
+   *                         ElemHide.SPECIFIC_ONLY.
    * @param {Boolean} [provideFilterKeys]
-   * If true, the function will return a list of corresponding filter keys in
-   * addition to selectors.
+   *   If true, the function will return a list of corresponding filter keys in
+   *   addition to selectors.
    * @returns {string[]|Array.<string[]>}
-   * List of selectors or an array with two elements (list of selectors and list
-   * of corresponding keys) if provideFilterKeys is true.
+   *   List of selectors or an array with two elements (list of selectors and
+   *   list of corresponding keys) if provideFilterKeys is true.
    */
   getSelectorsForDomain: function(domain, criteria, provideFilterKeys)
   {
     let filterKeys = [];
     let selectors = [];
 
     if (typeof criteria == "undefined")
       criteria = ElemHide.ALL_MATCHING;
     if (criteria < ElemHide.NO_UNCONDITIONAL)
     {
@@ skipping 35 matching lines @@
       let nextDot = currentDomain.indexOf(".");
       currentDomain = nextDot == -1 ? "" : currentDomain.substr(nextDot + 1);
     }
 
     if (provideFilterKeys)
       return [selectors, filterKeys];
     else
       return selectors;
   }
 };