add docstrings

backend/app/routes.py

@@ -13,7 +13,7 @@
 def index():
     """Provides basic documentation about the available resources"""
     return jsonify({
-        'description': 'Travel Time App backend root',
+        'description': 'Travel Time App backend',
         'endpoints': [
             {
                 'path': str(rule),
@@ -24,7 +24,9 @@ def index():
 
 # test URL /closest-node/-79.3400/43.6610
 @app.route('/nodes-within/<meters>/<longitude>/<latitude>', methods=['GET'])
-def closest_node(meters,longitude,latitude):
+def closest_node(meters, longitude, latitude):
+    """Returns up to 20 nodes within a given radius (in meters) of a point.
+    Nodes are selected from the Congestion Network, i.e. are fairly major intersections."""
     try:
         longitude = float(longitude)
         latitude = float(latitude)
@@ -36,6 +38,8 @@ def closest_node(meters,longitude,latitude):
 # test URL /node/30357505
 @app.route('/node/<node_id>', methods=['GET'])
 def node(node_id):
+    """Returns information about a given node in the Here street network.
+    This uses the latest map version and may not recognize an older node_id."""
     try:
         node_id = int(node_id)
     except:
@@ -46,7 +50,8 @@ def node(node_id):
 #shell function - outputs json for use on frontend
 @app.route('/link-nodes/<from_node_id>/<to_node_id>', methods=['GET'])
 def get_links_between_two_nodes(from_node_id, to_node_id):
-    """Returns links of the shortest path between two nodes on the HERE network"""
+    """Returns links of the shortest path between two nodes on the HERE network,
+    including link_dir IDs, link geometries, and lengths in meters."""
     try:
         from_node_id = int(from_node_id)
         to_node_id = int(to_node_id)
@@ -79,12 +84,18 @@ def get_links_between_two_nodes(from_node_id, to_node_id):
     '/aggregate-travel-times/<start_node>/<end_node>/<start_time>/<end_time>/<start_date>/<end_date>/<include_holidays>/<dow_str>',
     methods=['GET']
 )
-# - start_node, end_node (int): the congestion network / HERE node_id's
-# - start_time, end_time (int): starting (inclusive), ending (exclusive) hours of aggregation
-# - start_date, end_date (YYYY-MM-DD): start (inclusive), end (exclusive) date of aggregation
-# - include_holidays(str, boolean-ish): 'true' will include holidays
-# - dow_list(str): flattened list of integers, i.e. [1,2,3,4] -> '1234', representing days of week to be included (ISODOW)
 def aggregate_travel_times(start_node, end_node, start_time, end_time, start_date, end_date, include_holidays, dow_str):
+    """
+    Aggregates travel times, returning averaged travel times along the selected corridor during the specified dates and times.
+    Also returns some helpful diagnostic data such as the parsed query args, the route identified between the nodes, and some measures of sampling error.
+
+    Arguments:
+    start_node, end_node (int): HERE network node_id's
+    start_time, end_time (int): starting (inclusive), ending (exclusive) hours
+    start_date, end_date (YYYY-MM-DD): start (inclusive), end (exclusive) dates
+    include_holidays(str, boolean-ish): 'true' will include holidays, 'false' will exclude them
+    dow_list(str): flattened list of integers, i.e. [1,2,3,4] -> '1234', representing days of week to be included; ISODOW specification
+    """
     try:
         start_node = int(start_node)
         end_node = int(end_node)
@@ -122,6 +133,7 @@ def aggregate_travel_times(start_node, end_node, start_time, end_time, start_dat
 # test URL /date-bounds
 @app.route('/date-range', methods=['GET'])
 def get_date_bounds():
+    """Returns the dates of the earliest and latest available travel time data."""
     connection = getConnection()
     with connection:
         with connection.cursor() as cursor:
@@ -136,7 +148,7 @@ def get_date_bounds():
 # test URL /holidays
 @app.route('/holidays', methods=['GET'])
 def get_holidays():
-    "Return dates of all known holidays in ascending order"
+    "Return dates of all Ontario holidays in ascending order. These should fully cover any available travel time data."
     connection = getConnection()
     query = f"""
     SELECT