Improves the `tf.QueueBase` documentation with regard to error conditions.

Fixes #2326.
Change: 124364329

1 files changed, 48 insertions, 12 deletions

diff --git a/tensorflow/python/ops/data_flow_ops.py b/tensorflow/python/ops/data_flow_ops.py
index 9c6feb4ed7..5f53b3dbc5 100644
--- a/tensorflow/python/ops/data_flow_ops.py
+++ b/tensorflow/python/ops/data_flow_ops.py
@@ -276,6 +276,15 @@ class QueueBase(object):
     If the queue is full when this operation executes, it will block
     until the element has been enqueued.
 
+    At runtime, this operation may raise an error if the queue is
+    [closed](#QueueBase.close) before or during its execution. If the
+    queue is closed before this operation runs,
+    `tf.errors.AbortedError` will be raised. If this operation is
+    blocked, and either (i) the queue is closed by a close operation
+    with `cancel_pending_enqueues=True`, or (ii) the session is
+    [closed](../../api_docs/python/client.md#Session.close),
+    `tf.errors.CancelledError` will be raised.
+
     Args:
       vals: A tensor, a list or tuple of tensors, or a dictionary containing
         the values to enqueue.
@@ -305,6 +314,15 @@ class QueueBase(object):
     If the queue is full when this operation executes, it will block
     until all of the elements have been enqueued.
 
+    At runtime, this operation may raise an error if the queue is
+    [closed](#QueueBase.close) before or during its execution. If the
+    queue is closed before this operation runs,
+    `tf.errors.AbortedError` will be raised. If this operation is
+    blocked, and either (i) the queue is closed by a close operation
+    with `cancel_pending_enqueues=True`, or (ii) the session is
+    [closed](../../api_docs/python/client.md#Session.close),
+    `tf.errors.CancelledError` will be raised.
+
     Args:
       vals: A tensor, a list or tuple of tensors, or a dictionary
         from which the queue elements are taken.
@@ -357,6 +375,14 @@ class QueueBase(object):
     If the queue is empty when this operation executes, it will block
     until there is an element to dequeue.
 
+    At runtime, this operation may raise an error if the queue is
+    [closed](#QueueBase.close) before or during its execution. If the
+    queue is closed, the queue is empty, and there are no pending
+    enqueue operations that can fulfil this request,
+    `tf.errors.OutOfRangeError` will be raised. If the session is
+    [closed](../../api_docs/python/client.md#Session.close),
+    `tf.errors.CancelledError` will be raised.
+
     Args:
       name: A name for the operation (optional).
 
@@ -386,6 +412,14 @@ class QueueBase(object):
     If the queue is closed and there are less than `n` elements left, then an
     `OutOfRange` exception is raised.
 
+    At runtime, this operation may raise an error if the queue is
+    [closed](#QueueBase.close) before or during its execution. If the
+    queue is closed, the queue contains fewer than `n` elements, and
+    there are no pending enqueue operations that can fulfil this
+    request, `tf.errors.OutOfRangeError` will be raised. If the
+    session is [closed](../../api_docs/python/client.md#Session.close),
+    `tf.errors.CancelledError` will be raised.
+
     Args:
       n: A scalar `Tensor` containing the number of elements to dequeue.
       name: A name for the operation (optional).
@@ -412,18 +446,20 @@ class QueueBase(object):
     """Dequeues and concatenates `n` elements from this queue.
 
     **Note** This operation is not supported by all queues.  If a queue does not
-    support DequeueUpTo, then an Unimplemented exception is raised.
-
-    This operation concatenates queue-element component tensors along the
-    0th dimension to make a single component tensor.  All of the components
-    in the dequeued tuple will have size `n` in the 0th dimension.
-
-    If the queue is closed and there are more than `0` but less than `n`
-    elements remaining, then instead of raising an `OutOfRange` exception like
-    `dequeue_many`, the remaining elements are returned immediately.
-    If the queue is closed and there are `0` elements left in the queue, then
-    an `OutOfRange` exception is raised just like in `dequeue_many`.
-    Otherwise the behavior is identical to `dequeue_many`:
+    support DequeueUpTo, then a `tf.errors.UnimplementedError` is raised.
+
+    This operation concatenates queue-element component tensors along
+    the 0th dimension to make a single component tensor. If the queue
+    has not been closed, all of the components in the dequeued tuple
+    will have size `n` in the 0th dimension.
+
+    If the queue is closed and there are more than `0` but fewer than
+    `n` elements remaining, then instead of raising a
+    `tf.errors.OutOfRangeError` like [`dequeue_many`](#QueueBase.dequeue_many),
+    the remaining elements are returned immediately.  If the queue is
+    closed and there are `0` elements left in the queue, then a
+    `tf.errors.OutOfRangeError` is raised just like in `dequeue_many`.
+    Otherwise the behavior is identical to `dequeue_many`.
 
     Args:
       n: A scalar `Tensor` containing the number of elements to dequeue.