update docstrings

osmnx/distance.py

@@ -306,13 +306,15 @@ def nearest_nodes(
     """
     Find the nearest node to a point or to each of several points.
 
-    If `X` and `Y` are single coordinate values, this will return the nearest
-    node to that point. If `X` and `Y` are iterables of coordinate values,
-    this will return the nearest node to each point.
+    If `X` and `Y` are single coordinate values, this function will return the
+    nearest node to that point. If `X` and `Y` are iterables of coordinate
+    values, it will return the nearest node to each point.
 
-    If the graph is projected, this uses a k-d tree for Euclidean nearest
+    This function is vectorized: if you have many points to search for, pass
+    them in one call as numpy arrays (avoid using loops) to maximize runtime
+    speed. If the graph is projected, it uses a k-d tree for Euclidean nearest
     neighbor search, which requires that scipy is installed as an optional
-    dependency. If it is unprojected, this uses a ball tree for haversine
+    dependency. If the graph is unprojected, it uses a ball tree for haversine
     nearest neighbor search, which requires that scikit-learn is installed as
     an optional dependency.
 
@@ -463,11 +465,15 @@ def nearest_edges(
     """
     Find the nearest edge to a point or to each of several points.
 
-    If `X` and `Y` are single coordinate values, this will return the nearest
-    edge to that point. If `X` and `Y` are iterables of coordinate values,
-    this will return the nearest edge to each point. This uses an R-tree
-    spatial index and minimizes the Euclidean distance from each point to the
-    possible matches. For accurate results, use a projected graph and points.
+    If `X` and `Y` are single coordinate values, this function will return the
+    nearest edge to that point. If `X` and `Y` are iterables of coordinate
+    values, it will return the nearest edge to each point.
+
+    This function is vectorized: if you have many points to search for, pass
+    them in one call as numpy arrays (avoid using loops) to maximize runtime
+    speed. It uses an R-tree spatial index and minimizes the Euclidean
+    distance from each point to the possible matches. For accurate results,
+    use a projected graph and projected points.
 
     Parameters
     ----------
@@ -481,7 +487,7 @@ def nearest_edges(
         containing no nulls.
     return_dist
         If True, optionally also return the distance(s) between point(s) and
-        nearest edge(s).
+        nearest edge(s), in same units as graph and points.
 
     Returns
     -------

osmnx/features.py

@@ -123,6 +123,7 @@ def features_from_bbox(
     Returns
     -------
     gdf
+        The features, multi-indexed by element type and OSM ID.
     """
     # convert bbox to polygon then create GeoDataFrame of features within it
     polygon = utils_geo.bbox_to_poly(bbox)
@@ -167,6 +168,7 @@ def features_from_point(
     Returns
     -------
     gdf
+        The features, multi-indexed by element type and OSM ID.
     """
     # create bbox from point and dist, then create gdf of features within it
     bbox = utils_geo.bbox_from_point(center_point, dist)
@@ -209,6 +211,7 @@ def features_from_address(
     Returns
     -------
     gdf
+        The features, multi-indexed by element type and OSM ID.
     """
     # geocode the address to a point, then create gdf of features around it
     center_point = geocoder.geocode(address)
@@ -265,6 +268,7 @@ def features_from_place(
     Returns
     -------
     gdf
+        The features, multi-indexed by element type and OSM ID.
     """
     # extract the geometry from the GeoDataFrame to use in query
     polygon = geocoder.geocode_to_gdf(query, which_result=which_result).union_all()
@@ -308,6 +312,7 @@ def features_from_polygon(
     Returns
     -------
     gdf
+        The features, multi-indexed by element type and OSM ID.
     """
     # verify that the geometry is valid and is a Polygon/MultiPolygon
     if not polygon.is_valid:
@@ -356,6 +361,7 @@ def features_from_xml(
     Returns
     -------
     gdf
+        The features, multi-indexed by element type and OSM ID.
     """
     # if tags or polygon is None, create an empty object to skip filtering
     if tags is None:

osmnx/routing.py

@@ -507,6 +507,10 @@ def add_edge_speeds(
     the edge's maxspeed attribute string, then function assumes kph, per OSM
     guidelines: https://wiki.openstreetmap.org/wiki/Map_Features/Units
 
+    If you wish to set all edge speeds to a single constant value (such as for
+    a walking network), use `nx.set_edge_attributes` to set the `speed_kph`
+    attribute value directly, rather than using this function.
+
     Parameters
     ----------
     G