From 531e6de7bbbd484743b2097949044853940c42dd Mon Sep 17 00:00:00 2001
From: Diptorup Deb <diptorup.deb@intel.com>
Date: Sat, 8 Apr 2023 01:15:40 -0500
Subject: [PATCH] Add API doc for get_device_cached_queue

---
 dpctl/__init__.py             |  2 ++
 dpctl/_sycl_queue_manager.pyx | 19 +++++++++++++++++--
 2 files changed, 19 insertions(+), 2 deletions(-)

diff --git a/dpctl/__init__.py b/dpctl/__init__.py
index 3784e6006d..be89c38113 100644
--- a/dpctl/__init__.py
+++ b/dpctl/__init__.py
@@ -66,6 +66,7 @@
     get_current_backend,
     get_current_device_type,
     get_current_queue,
+    get_device_cached_queue,
     get_num_activated_queues,
     is_in_device_context,
     nested_context_factories,
@@ -123,6 +124,7 @@
     "get_current_backend",
     "get_current_device_type",
     "get_current_queue",
+    "get_device_cached_queue",
     "get_num_activated_queues",
     "is_in_device_context",
     "nested_context_factories",
diff --git a/dpctl/_sycl_queue_manager.pyx b/dpctl/_sycl_queue_manager.pyx
index 15df68e034..179adeac71 100644
--- a/dpctl/_sycl_queue_manager.pyx
+++ b/dpctl/_sycl_queue_manager.pyx
@@ -39,14 +39,15 @@ from ._sycl_context cimport SyclContext
 from ._sycl_device cimport SyclDevice
 
 __all__ = [
+    "_global_device_queue_cache",
     "device_context",
     "get_current_backend",
     "get_current_device_type",
     "get_current_queue",
+    "get_device_cached_queue",
     "get_num_activated_queues",
     "is_in_device_context",
     "set_global_queue",
-    "_global_device_queue_cache",
 ]
 
 _logger = logging.getLogger(__name__)
@@ -344,7 +345,21 @@ _global_device_queue_cache = ContextVar(
 
 
 cpdef object get_device_cached_queue(object key):
-    """Get cached queue associated with given device"""
+    """Returns a cached queue associated with given device.
+
+    Args:
+        key : Either a 2-tuple consisting of a :class:`dpctl.SyclContext` and
+            a :class:`dpctl.SyclDevice`, or a :class:`dpctl.SyclDevice`
+            instance, or a filter string identifying a device.
+
+    Returns:
+        :class:`dpctl.SyclQueue`: A cached SYCL queue associated with the
+        input device.
+
+    Raises:
+        TypeError: If the input key is not one of the accepted types.
+
+    """
     _cache = _global_device_queue_cache.get()
     q_, changed_ = _cache.get_or_create(key)
     if changed_: _global_device_queue_cache.set(_cache)