[autoscaler] Try to improve the request_resources() documentation (#12465)

python/ray/autoscaler/sdk.py

@@ -183,18 +183,28 @@ def get_worker_node_ips(cluster_config: Union[dict, str]) -> List[str]:
 
 def request_resources(num_cpus: Optional[int] = None,
                       bundles: Optional[List[dict]] = None) -> None:
-    """Remotely request some CPU or GPU resources from the autoscaler.
+    """Command the autoscaler to scale to accommodate the specified requests.
 
-    This function is to be called e.g. on a node before submitting a bunch of
-    ray.remote calls to ensure that resources rapidly become available.
+    The cluster will immediately attempt to scale to accommodate the requested
+    resources, bypassing normal upscaling speed constraints. This takes into
+    account existing resource usage.
+
+    For example, suppose you call ``request_resources(num_cpus=100)`` and
+    there are 45 currently running tasks, each requiring 1 CPU. Then, enough
+    nodes will be added so up to 100 tasks can run concurrently. It does
+    **not** add enough nodes so that 145 tasks can run.
+
+    This call is only a hint to the autoscaler. The actual resulting cluster
+    size may be slightly larger or smaller than expected depending on the
+    internal bin packing algorithm and max worker count restrictions.
 
     Args:
         num_cpus (int): Scale the cluster to ensure this number of CPUs are
             available. This request is persistent until another call to
-            request_resources() is made.
+            request_resources() is made to override.
         bundles (List[ResourceDict]): Scale the cluster to ensure this set of
             resource shapes can fit. This request is persistent until another
-            call to request_resources() is made.
+            call to request_resources() is made to override.
 
     Examples:
         >>> # Request 1000 CPUs.