added comments and syntax updates

controller/libpostal.js

@@ -13,6 +13,7 @@ function setup(should_execute) {
     const parsed_text = text_analyzer.parse(req.clean.text);
 
     if (!_.isUndefined(parsed_text)) {
+      // if a known ISO2 country was parsed, convert it to ISO3
       if (_.has(parsed_text, 'country') && iso3166.is2(_.toUpper(parsed_text.country))) {
         parsed_text.country = iso3166.to3(_.toUpper(parsed_text.country));
       }

controller/placeholder.js

@@ -98,6 +98,7 @@ function getBoundaryCountryFilter(clean, geometric_filters_apply) {
 // return a function that detects if a result is inside a bbox if a bbox is available
 // if there's no bbox, return a function that always returns true
 function getBoundaryRectangleFilter(clean, geometric_filters_apply) {
+  // check to see if boundary.rect.min_lat/min_lon/max_lat/max_lon are all available
   if (geometric_filters_apply && ['min_lat', 'min_lon', 'max_lat', 'max_lon'].every((f) => {
     return _.has(clean, `boundary.rect.${f}`);
   })) {
@@ -107,12 +108,14 @@ function getBoundaryRectangleFilter(clean, geometric_filters_apply) {
       { latitude: clean['boundary.rect.max_lat'], longitude: clean['boundary.rect.max_lon'] },
       { latitude: clean['boundary.rect.min_lat'], longitude: clean['boundary.rect.max_lon'] }
     ];
+    // isPointInside takes polygon last, so create a function that has it pre-populated
     const isPointInsidePolygon = _.partialRight(geolib.isPointInside, polygon);
 
     return _.partial(isInsideGeometry, isPointInsidePolygon);
 
   }
 
+  // there's no bbox filter, so return a function that always returns true
   return () => true;
 
 }
@@ -120,6 +123,7 @@ function getBoundaryRectangleFilter(clean, geometric_filters_apply) {
 // return a function that detects if a result is inside a circle if a circle is available
 // if there's no circle, return a function that always returns true
 function getBoundaryCircleFilter(clean, geometric_filters_apply) {
+  // check to see if boundary.circle.lat/lon/radius are all available
   if (geometric_filters_apply && ['lat', 'lon', 'radius'].every((f) => {
     return _.has(clean, `boundary.circle.${f}`);
   })) {
@@ -128,12 +132,15 @@ function getBoundaryCircleFilter(clean, geometric_filters_apply) {
       longitude: clean['boundary.circle.lon']
     };
     const radiusInMeters = clean['boundary.circle.radius'] * 1000;
+
+    // isPointInCircle takes circle/radius last, so create a function that has them pre-populated
     const isPointInCircle = _.partialRight(geolib.isPointInCircle, center, radiusInMeters);
 
     return _.partial(isInsideGeometry, isPointInCircle);
 
   }
 
+  // there's no circle filter, so return a function that always returns true
   return () => true;
 
 }
@@ -143,6 +150,7 @@ function isInsideGeometry(f, result) {
   return hasLatLon(result) ? f(getLatLon(result)) : false;
 }
 
+// returns true if hierarchyElement has both name and id
 function placetypeHasNameAndId(hierarchyElement) {
   return !_.isEmpty(_.trim(hierarchyElement.name)) &&
           !_.isEmpty(_.trim(hierarchyElement.id));

controller/predicates/has_any_parsed_text_property.js

@@ -7,6 +7,7 @@ module.exports = function() {
   // save off requested properties since arguments can't be referenced later
   const properties = _.values(arguments);
 
+  // return true if any of the supplied properties are in clean.parsed_text
   return (request, response) => !_.isEmpty(
     _.intersection(
       properties,

controller/predicates/has_request_parameter.js

@@ -1,3 +1,3 @@
 const _ = require('lodash');
 
-module.exports = (parameter) => (req, res) => _.has(req, ['clean', parameter]);
+module.exports = (parameter) => (req, res) => (_.has(req, ['clean', parameter]));

controller/predicates/is_addressit_parse.js

@@ -1,4 +1,4 @@
 const _ = require('lodash');
 
 // returns true iff req.clean.parser is addressit
-module.exports = (req, res) => _.get(req, 'clean.parser') === 'addressit';
+module.exports = (req, res) => (_.get(req, 'clean.parser') === 'addressit');

controller/predicates/is_only_non_admin_layers.js

@@ -1,5 +1,7 @@
 const _ = require('lodash');
 
 // return IFF req.clean.layers is empty OR there are non-venue/address/street layers
-module.exports = (req, res) => !_.isEmpty(_.get(req, 'clean.layers', [])) &&
+module.exports = (req, res) => (
-  _.isEmpty(_.difference(req.clean.layers, ['venue', 'address', 'street']));
+  !_.isEmpty(_.get(req, 'clean.layers', [])) &&
+  _.isEmpty(_.difference(req.clean.layers, ['venue', 'address', 'street']))
+);

controller/predicates/is_request_sources_only_whosonfirst.js

@@ -1,3 +1,9 @@
 const _ = require('lodash');
 
-module.exports = (req, res) => _.isEqual(_.get(req, 'clean.sources', []), ['whosonfirst']);
+// returns true IFF clean.sources only contains 'whosonfirst'
+module.exports = (req, res) => (
+  _.isEqual(
+    _.get(req, 'clean.sources', []),
+    ['whosonfirst']
+  )
+);