Pub/Sub: surface publish future in documentation (googleapis#8229)

anguillanneuf · plamut · commit cd57e656c94f · 2019-06-06T18:56:22.000+02:00
* surface publish future in documentation

* Update class definition
diff --git a/pubsub/docs/publisher/api/futures.rst b/pubsub/docs/publisher/api/futures.rst
@@ -0,0 +1,6 @@
+Futures
+=======
+
+.. automodule:: google.cloud.pubsub_v1.publisher.futures
+  :members:
+  :inherited-members:
diff --git a/pubsub/docs/publisher/index.rst b/pubsub/docs/publisher/index.rst
@@ -95,7 +95,7 @@ Futures
 -------
 
 Every call to :meth:`~.pubsub_v1.publisher.client.Client.publish` returns
-an instance of :class:`google.api_core.future.Future`.
+an instance of :class:`~.pubsub_v1.publisher.futures.Future`.
 
 .. note::
    
@@ -135,3 +135,4 @@ API Reference
   :maxdepth: 2
 
   api/client
+  api/futures
diff --git a/pubsub/google/cloud/pubsub_v1/publisher/futures.py b/pubsub/google/cloud/pubsub_v1/publisher/futures.py
@@ -1,4 +1,4 @@
-# Copyright 2017, Google LLC All rights reserved.
+# Copyright 2019, Google LLC All rights reserved.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -18,22 +18,11 @@
 
 
 class Future(futures.Future):
-    """Encapsulation of the asynchronous execution of an action.
-
-    This object is returned from asychronous Pub/Sub publishing calls, and is
-    the interface to determine the status of those calls.
-
-    This object should not be created directly, but is returned by other
-    methods in this library.
-
-    Args:
-        completed (Optional[Any]): An event, with the same interface as
-            :class:`threading.Event`. This is provided so that callers
-            with different concurrency models (e.g. ``threading`` or
-            ``multiprocessing``) can supply an event that is compatible
-            with that model. The ``wait()`` and ``set()`` methods will be
-            used. If this argument is not provided, then a new
-            :class:`threading.Event` will be created and used.
+    """This future object is returned from asychronous Pub/Sub publishing
+    calls.
+
+    Calling :meth:`result` will resolve the future by returning the message
+    ID, unless an error occurs.
     """
 
     def result(self, timeout=None):
