Added documentation and an generic implementation of details.

web/js/ndbDatabase.js

@@ -1,70 +1,108 @@
-angular.module('ndbDatabase', ['ngResource'])
-    .factory('NDBSearch', ['$resource', '$q', function($resource, $q) {
-        return $resource('https://api.nal.usda.gov/ndb/search?'+
-                         'q=:query&ds=Standard+Reference&api_key=:key&fg=:groups&max=:max&offset=:offset', {}, {
-                             get: {method: "GET",
-                                   isArray: true,
-                                   transformRequest: function(data, headers) {
-                                       return angular.extend({}, headers, {'Content-Type': 'application/json'});
-                                   },
-                                   headers: {
-                                       'Content-Type': 'application/json'
-                                   },
-                                   transformResponse: function(data, headersGetter, status) {
-                                       var json = angular.fromJson(data);
-                                       return status < 400 && json.list? json.list.item : json.errors.error;
-                                   }
-                                  }
-                         });
-    }]).factory('NDBList', ['$resource', '$q', function($resource, $q) {
-        return $resource('https://api.nal.usda.gov/ndb/list?' +
-                         'api_key=:key&lt=:type&nutrients=:nutrients&fg=:groups&max=:max&offset=:offset', {}, {
-                             get: {method: "GET",
-                                   isArray: true,
-                                   transformRequest: function(data, headers) {
-                                       return angular.extend({}, headers, {'Content-Type': 'application/json'});
-                                   },
-                                   headers: {
-                                       'Content-Type': 'application/json'
-                                   },
-                                   transformResponse: function(data, headersGetter, status) {
-                                       var json = angular.fromJson(data);
-                                       return status < 400 && json.list? json.list.item : json.errors.error;
-                                   }
-                                  }
-                         });
-    }]).factory('NDBReport', ['$resource', '$q', function($resource, $q) {
-        return $resource('https://api.nal.usda.gov/ndb/reports/?api_key=:key&ndbno=:ndbno', {}, {
-            get: {method: "GET",
-                  transformRequest: function(data, headers) {
-                      return angular.extend({}, headers, {
-                          'Content-Type': 'application/json'
-                      });
-                  },
-                  headers: {
-                      'Content-Type': 'application/json'
-                  },
-                  transformResponse: function(data, headersGetter, status) {
-                      var json = angular.fromJson(data);
-                      return status < 400 && json.report.food? json.report.food : json.errors.error;
-                  }
-                 }
-        });
-    }]).factory('NDBNutrients', ['$resource', '$q', function($resource, $q) {
-        return $resource('https://api.nal.usda.gov/ndb/nutrients?'+
-                         'api_key=:key&nbno=:nums&nutrients=:nutrients&fg=:groups&max=:max&offset=:offset', {}, {
-                             get: {method: "GET",
-                                   isArray: true,
-                                   transformRequest: function(data, headers) {
-                                       return angular.extend({}, headers, {'Content-Type': 'application/json'});
-                                   },
-                                   headers: {
-                                       'Content-Type': 'application/json'
-                                   },
-                                   transformResponse: function(data, headersGetter, status) {
-                                       var json = angular.fromJson(data);
-                                       return status < 400 && json.list? json.list.item : json.errors.error;
-                                   }
-                                  }
-                         });
-    }]);
+/**
+ * Provides interface for ndb database.
+ * 
+ * See the <a href="https://ndb.nal.usda.gov/ndb/doc/apilist/API-FOOD-REPORTV2.md">
+ * official documentation</a> for details.
+ */
+(function() {
+    // Methods description for ndb APIs that return a list.
+    var listMethod = {
+        get: {
+            method: "GET",
+            isArray: true,
+            transformRequest: function(data, headers) {
+                return angular.extend({}, headers, {'Content-Type': 'application/json'});
+            },
+            headers: {
+                'Content-Type': 'application/json'
+            },
+            transformResponse: function(data, headersGetter, status) {
+                var json = angular.fromJson(data);
+                return status < 400 && json.list? json.list.item : json.errors.error;
+            }
+        }
+    };
+    // Methods description for ndb APIs that return a report.
+    var reportMethod = {
+        get: {
+            method: "GET",
+            transformRequest: function(data, headers) {
+                return angular.extend({}, headers, {
+                    'Content-Type': 'application/json'
+                });
+            },
+            headers: {
+                'Content-Type': 'application/json'
+            },
+            transformResponse: function(data, headersGetter, status) {
+                var json = angular.fromJson(data);
+                return status < 400 && json.report.food? json.report.food : json.errors.error;
+            }
+        }
+    };
+    angular.module('ndbDatabase', ['ngResource'])
+    /*
+     * Query the usda ndb database for a list of elements by keyword.
+     *
+     * See <a href="https://ndb.nal.usda.gov/ndb/doc/apilist/API-SEARCH.md">official reference</a> for details.
+     * 
+     * @param key USDA NDB api key.
+     * @param query Keywords to search
+     * @param fg Food group ID
+     * @param max Maximum number of items to return
+     * @param offset Beginning item in the result set
+     * @param sort Either n=name or id. (id varies by type: nutrient number for nutrients, NDBno for foods, food group id for food groups)
+     * @returns A list of ndb items matching the query.
+     */
+        .factory('NDBSearch', ['$resource', function($resource) {
+            return $resource('https://api.nal.usda.gov/ndb/search?'+
+                             'q=:query&ds=Standard+Reference&api_key=:key&fg=:groups&max=:max&offset=:offset', {}, listMethod);
+        }])
+    /*
+     * Query the usda ndb database for a list of elements.
+     *
+     * See <a href="https://ndb.nal.usda.gov/ndb/doc/apilist/API-LIST.md">official reference</a> for details.
+     * 
+     * @param key USDA NDB api key.
+     * @param type One of d = derivation codes, f = food , n = all nutrients, ns = speciality nutrients, nr = standard release nutrients,g = food group
+     * @param max Maximum number of items to return
+     * @param offset Beginning item in the result set
+     * @param sort Either n=name or id. (id varies by type: nutrient number for nutrients, NDBno for foods, food group id for food groups)
+     * @returns A list of ndb items matching the type.
+     */
+        .factory('NDBList', ['$resource', function($resource) {
+            return $resource('https://api.nal.usda.gov/ndb/list?' +
+                             'api_key=:key&lt=:type&sort=:sort&max=:max&offset=:offset', {}, listMethod);
+        }])
+    /*
+     * Gets a detailed list of information about a food.
+     * 
+     * See <a href="https://ndb.nal.usda.gov/ndb/doc/apilist/API-FOOD-REPORT.md">official reference</a> for details.
+     * 
+     * @param key USDA NDB api key.
+     * @param ndbno Food id number
+     * @param type One of [b]asic or [f]ull or [s]tats
+     * @returns A report matching the ndb item.
+     */
+        .factory('NDBFood', ['$resource', function($resource) {
+            return $resource('https://api.nal.usda.gov/ndb/reports/?api_key=:key&ndbno=:ndbno&type=:type', {}, reportMethod);
+        }])
+    /*
+     * Gets a detailed list of information about the nutrients in a food.
+     *
+     * See <a href="https://ndb.nal.usda.gov/ndb/doc/apilist/API-NUTRIENT-REPORT.md">official reference</a> for details.
+     * 
+     * @param key USDA NDB api key.
+     * @param groups Food group ID
+     * @param max Maximum number of items to return
+     * @param offset Beginning item in the result set
+     * @param nums The food to look up
+     * @param nutrients A list of up to 20 nutrient_id's to include
+     * @param sort Either n=name or id. (id varies by type: nutrient number for nutrients, NDBno for foods, food group id for food groups)
+     * @returns A list of ndb items matching the query.
+     */
+        .factory('NDBNutrients', ['$resource', function($resource) {
+            return $resource('https://api.nal.usda.gov/ndb/nutrients?'+
+                             'api_key=:key&nbno=:nums&nutrients=:nutrients&fg=:groups&max=:max&offset=:offset&sort=:sort', {}, listMethod);
+        }]);
+})();