Noissue - Added documentation for exported functions to the "filterValidation" module

lib/filterValidation.js

 /*
  * This file is part of Adblock Plus <https://adblockplus.org/>,
  * Copyright (C) 2006-2015 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
  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  * GNU General Public License for more details.
  *
  * You should have received a copy of the GNU General Public License
  * along with Adblock Plus.  If not, see <http://www.gnu.org/licenses/>.
  */
 
 let {Filter, InvalidFilter, ElemHideBase} = require("filterClasses");
 
+/**
+ * Parses and validates a filter given by the user.
+ *
+ * @param {string}  text
+ * @param {Boolean} [ignore_headers=false]  If true, no exception is raised,
+ *                                          but null is returned instead,
+ *                                          if a filter list header is given.

[Wladimir Palant, 2015/03/02 20:45:15]

I have a hard time parsing that sentence :)

How about: "If true, no exception is raised for filter list headers, instead the
function will return null."

[Sebastian Noack, 2015/03/03 09:07:48]

Done.

+ * @return {Filter}
+ * @throws Will throw an error if filter cannot be parsed

[Wladimir Palant, 2015/03/02 20:45:15]

Nit: "throw an exception"?

[Sebastian Noack, 2015/03/03 09:07:48]

Done.

+ *         or contains an invalid CSS selector.
+ */
 function parseFilter(text, ignore_headers)
 {
   text = Filter.normalize(text);
   if (!text)
     return null;
 
   if (text[0] == "[")
   {
     if (ignore_headers)
       return null;
@@ skipping 21 matching lines @@
     catch (error)
     {
       throw ext.i18n.getMessage("invalid_css_selector", "'" + filter.selector + "'");
     }
   }
 
   return filter;
 }
 exports.parseFilter = parseFilter;
 
+/**
+ * Parses and validates a newline-separated list of filters given by the user.
+ *
+ * @param {string}  text
+ * @param {Boolean} [ignore_headers=false]  If true, filter list
+ *                                          headers are stripped.

[Wladimir Palant, 2015/03/02 20:45:15]

"If true, filter list headers will be stripped instead of raising an exception"?

[Sebastian Noack, 2015/03/03 09:07:48]

Done.

+ * @return {Filter[]}
+ * @throws Will throw an error if one of the filters cannot
+           be parsed or contains an invalid CSS selector.
+ */
 function parseFilters(text, ignore_headers)
 {
   let lines = text.split("\n");
   let filters = [];
 
   for (let i = 0; i < lines.length; i++)
   {
     let filter;
     try
     {
       filter = parseFilter(lines[i], ignore_headers);
     }
     catch (error)
     {
       throw ext.i18n.getMessage("line", (i + 1).toString()) + ": " + error;
     }
 
     if (filter)
       filters.push(filter);
   }
 
   return filters;
 }
 exports.parseFilters = parseFilters;