Emphasize that returned futures may differ from stdlib futures. (googleapis#6875)

tseaver · web-flow · commit f880e4e5fd12 · 2018-12-13T18:02:08.000-05:00
Closes googleapis#6201.
diff --git a/pubsub/docs/publisher/index.rst b/pubsub/docs/publisher/index.rst
@@ -94,8 +94,15 @@ batch can not exceed 10 megabytes.
 Futures
 -------
 
-Every call to :meth:`~.pubsub_v1.publisher.client.Client.publish` will return
-a class that conforms to the :class:`~concurrent.futures.Future` interface.
+Every call to :meth:`~.pubsub_v1.publisher.client.Client.publish` returns
+an instance of :class:`google.api_core.future.Future`.
+
+.. note::
+   
+   The returned future conforms for the most part to the interface of
+   the standard library's :class:`~concurrent.futures.Future`, but might not
+   be usable in all cases which expect that exact implementaton.
+
 You can use this to ensure that the publish succeeded:
 
 .. code-block:: python
diff --git a/pubsub/google/cloud/pubsub_v1/publisher/client.py b/pubsub/google/cloud/pubsub_v1/publisher/client.py
@@ -196,8 +196,9 @@ def publish(self, topic, data, **attrs):
                 sent as metadata. (These may be text strings or byte strings.)
 
         Returns:
-            ~concurrent.futures.Future: An object conforming to the
-            ``concurrent.futures.Future`` interface.
+            ~google.api_core.future.Future: An object conforming to the
+            ``concurrent.futures.Future`` interface (but not an instance
+            of that class).
         """
         # Sanity check: Is the data being sent as a bytestring?
         # If it is literally anything else, complain loudly about it.
