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

* surface publish future in documentation

* Update class definition

pubsub/docs/publisher/api/futures.rst

@@ -0,0 +1,6 @@
+Futures
+=======
+
+.. automodule:: google.cloud.pubsub_v1.publisher.futures
+ :members:
+ :inherited-members:

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

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):