diff --git a/artiq/coredevice/core.py b/artiq/coredevice/core.py
index ae0cb51a9..aa1bb8560 100644
--- a/artiq/coredevice/core.py
+++ b/artiq/coredevice/core.py
@@ -120,8 +120,28 @@ class Core:
 
     @kernel
     def get_cache(self, key):
+        """Extract a value from the core device cache.
+        After a value is extracted, it cannot be replaced with another value using
+        :meth:`put_cache` until all kernel functions finish executing; attempting
+        to replace it will result in a :class:`artiq.coredevice.exceptions.CacheError`.
+
+        If the cache does not contain any value associated with ``key``, an empty list
+        is returned.
+
+        The value is not copied, so mutating it will change what's stored in the cache.
+
+        :param str key: cache key
+        :return: a list of 32-bit integers
+        """
         return cache_get(key)
 
     @kernel
     def put_cache(self, key, value):
-        return cache_put(key, value)
+        """Put a value into the core device cache. The value will persist until reboot.
+
+        To remove a value from the cache, call :meth:`put_cache` with an empty list.
+
+        :param str key: cache key
+        :param list value: a list of 32-bit integers
+        """
+        cache_put(key, value)