add the method annotation and a comment explaining what's happening (#13306)

Change-Id: I848cc2f0beaed95340d9de7cca19a50c78d9da9a

python/ray/util/client/api.py

@@ -173,6 +173,27 @@ class ClientAPI:
         return self.worker.get_cluster_info(
             ray_client_pb2.ClusterInfoType.NODES)
 
+    def method(self, num_returns=1):
+        """Annotate an actor method
+
+        Args:
+            num_returns: The number of object refs that should be returned by
+                invocations of this actor method.
+        """
+
+        # NOTE: So this follows the same logic as in ray/actor.py::method()
+        # The reason to duplicate it here is to simplify the client mode
+        # redirection logic. As the annotated method gets pickled and sent to
+        # the server from the client it carries this private variable, it
+        # activates the same logic on the server side; so there's no need to
+        # pass anything else. It's inside the class definition that becomes an
+        # actor. Similar annotations would follow the same way.
+        def annotate_method(method):
+            method.__ray_num_returns__ = num_returns
+            return method
+
+        return annotate_method
+
     def cluster_resources(self):
         """Get the current total cluster resources.