diff --git a/docs/library/pyb.rst b/docs/library/pyb.rst
index 2ceed23968..1e1e9ffaab 100644
--- a/docs/library/pyb.rst
+++ b/docs/library/pyb.rst
@@ -212,8 +212,13 @@ Miscellaneous functions
 
 .. function:: mount(device, mountpoint, \*, readonly=False, mkfs=False)
 
+   .. note:: This function is deprecated. Mounting and unmounting devices should
+      be performed by :meth:`uos.mount` and :meth:`uos.umount` instead.
+
    Mount a block device and make it available as part of the filesystem.
-   ``device`` must be an object that provides the block protocol:
+   ``device`` must be an object that provides the block protocol. (The
+   following is also deprecated. See :class:`uos.AbstractBlockDev` for the
+   correct way to create a block device.)
 
     - ``readblocks(self, blocknum, buf)``
     - ``writeblocks(self, blocknum, buf)`` (optional)
@@ -238,9 +243,6 @@ Miscellaneous functions
    If ``mkfs`` is ``True``, then a new filesystem is created if one does not
    already exist.
 
-   To unmount a device, pass ``None`` as the device and the mount location
-   as ``mountpoint``.
-
 .. function:: repl_uart(uart)
 
    Get or set the UART object where the REPL is repeated on.