Add missing docstrings

docs/source/reference-lowlevel.rst

@@ -257,6 +257,12 @@ anything real. See `#26
 .. function:: wait_overlapped(handle, lpOverlapped)
    :async:
 
+.. function:: write_overlapped(handle, data)
+   :async:
+
+.. function:: readinto_overlapped(handle, data)
+   :async:
+
 .. function:: current_iocp()
 
 .. function:: monitor_completion_key()

src/trio/_core/_generated_io_epoll.py

@@ -16,6 +16,27 @@
 
 
 async def wait_readable(fd: (int | _HasFileNo)) -> None:
+    """Block until the kernel reports that the given object is readable.
+
+    On Unix systems, ``fd`` must either be an integer file descriptor,
+    or else an object with a ``.fileno()`` method which returns an
+    integer file descriptor. Any kind of file descriptor can be passed,
+    though the exact semantics will depend on your kernel. For example,
+    this probably won't do anything useful for on-disk files.
+
+    On Windows systems, ``fd`` must either be an integer ``SOCKET``
+    handle, or else an object with a ``.fileno()`` method which returns
+    an integer ``SOCKET`` handle. File descriptors aren't supported,
+    and neither are handles that refer to anything besides a
+    ``SOCKET``.
+
+    :raises trio.BusyResourceError:
+        if another task is already waiting for the given socket to
+        become readable.
+    :raises trio.ClosedResourceError:
+        if another task calls :func:`notify_closing` while this
+        function is still working.
+    """
     locals()[LOCALS_KEY_KI_PROTECTION_ENABLED] = True
     try:
         return await GLOBAL_RUN_CONTEXT.runner.io_manager.wait_readable(fd)
@@ -24,6 +45,17 @@ async def wait_readable(fd: (int | _HasFileNo)) -> None:
 
 
 async def wait_writable(fd: (int | _HasFileNo)) -> None:
+    """Block until the kernel reports that the given object is writable.
+
+    See `wait_readable` for the definition of ``fd``.
+
+    :raises trio.BusyResourceError:
+        if another task is already waiting for the given socket to
+        become writable.
+    :raises trio.ClosedResourceError:
+        if another task calls :func:`notify_closing` while this
+        function is still working.
+    """
     locals()[LOCALS_KEY_KI_PROTECTION_ENABLED] = True
     try:
         return await GLOBAL_RUN_CONTEXT.runner.io_manager.wait_writable(fd)
@@ -32,6 +64,30 @@ async def wait_writable(fd: (int | _HasFileNo)) -> None:
 
 
 def notify_closing(fd: (int | _HasFileNo)) -> None:
+    """Notify waiters of the given object that it will be closed.
+
+    Call this before closing a file descriptor (on Unix) or socket (on
+    Windows). This will cause any `wait_readable` or `wait_writable`
+    calls on the given object to immediately wake up and raise
+    `~trio.ClosedResourceError`.
+
+    This doesn't actually close the object – you still have to do that
+    yourself afterwards. Also, you want to be careful to make sure no
+    new tasks start waiting on the object in between when you call this
+    and when it's actually closed. So to close something properly, you
+    usually want to do these steps in order:
+
+    1. Explicitly mark the object as closed, so that any new attempts
+       to use it will abort before they start.
+    2. Call `notify_closing` to wake up any already-existing users.
+    3. Actually close the object.
+
+    It's also possible to do them in a different order if that's more
+    convenient, *but only if* you make sure not to have any checkpoints in
+    between the steps. This way they all happen in a single atomic
+    step, so other tasks won't be able to tell what order they happened
+    in anyway.
+    """
     locals()[LOCALS_KEY_KI_PROTECTION_ENABLED] = True
     try:
         return GLOBAL_RUN_CONTEXT.runner.io_manager.notify_closing(fd)

src/trio/_core/_generated_io_kqueue.py

@@ -20,6 +20,10 @@
 
 
 def current_kqueue() -> select.kqueue:
+    """TODO: these are implemented, but are currently more of a sketch than
+    anything real. See `#26
+    <https://github.com/python-trio/trio/issues/26>`__.
+    """
     locals()[LOCALS_KEY_KI_PROTECTION_ENABLED] = True
     try:
         return GLOBAL_RUN_CONTEXT.runner.io_manager.current_kqueue()
@@ -30,6 +34,10 @@ def current_kqueue() -> select.kqueue:
 def monitor_kevent(
     ident: int, filter: int
 ) -> ContextManager[_core.UnboundedQueue[select.kevent]]:
+    """TODO: these are implemented, but are currently more of a sketch than
+    anything real. See `#26
+    <https://github.com/python-trio/trio/issues/26>`__.
+    """
     locals()[LOCALS_KEY_KI_PROTECTION_ENABLED] = True
     try:
         return GLOBAL_RUN_CONTEXT.runner.io_manager.monitor_kevent(ident, filter)
@@ -40,6 +48,10 @@ def monitor_kevent(
 async def wait_kevent(
     ident: int, filter: int, abort_func: Callable[[RaiseCancelT], Abort]
 ) -> Abort:
+    """TODO: these are implemented, but are currently more of a sketch than
+    anything real. See `#26
+    <https://github.com/python-trio/trio/issues/26>`__.
+    """
     locals()[LOCALS_KEY_KI_PROTECTION_ENABLED] = True
     try:
         return await GLOBAL_RUN_CONTEXT.runner.io_manager.wait_kevent(
@@ -50,6 +62,27 @@ async def wait_kevent(
 
 
 async def wait_readable(fd: (int | _HasFileNo)) -> None:
+    """Block until the kernel reports that the given object is readable.
+
+    On Unix systems, ``fd`` must either be an integer file descriptor,
+    or else an object with a ``.fileno()`` method which returns an
+    integer file descriptor. Any kind of file descriptor can be passed,
+    though the exact semantics will depend on your kernel. For example,
+    this probably won't do anything useful for on-disk files.
+
+    On Windows systems, ``fd`` must either be an integer ``SOCKET``
+    handle, or else an object with a ``.fileno()`` method which returns
+    an integer ``SOCKET`` handle. File descriptors aren't supported,
+    and neither are handles that refer to anything besides a
+    ``SOCKET``.
+
+    :raises trio.BusyResourceError:
+        if another task is already waiting for the given socket to
+        become readable.
+    :raises trio.ClosedResourceError:
+        if another task calls :func:`notify_closing` while this
+        function is still working.
+    """
     locals()[LOCALS_KEY_KI_PROTECTION_ENABLED] = True
     try:
         return await GLOBAL_RUN_CONTEXT.runner.io_manager.wait_readable(fd)
@@ -58,6 +91,17 @@ async def wait_readable(fd: (int | _HasFileNo)) -> None:
 
 
 async def wait_writable(fd: (int | _HasFileNo)) -> None:
+    """Block until the kernel reports that the given object is writable.
+
+    See `wait_readable` for the definition of ``fd``.
+
+    :raises trio.BusyResourceError:
+        if another task is already waiting for the given socket to
+        become writable.
+    :raises trio.ClosedResourceError:
+        if another task calls :func:`notify_closing` while this
+        function is still working.
+    """
     locals()[LOCALS_KEY_KI_PROTECTION_ENABLED] = True
     try:
         return await GLOBAL_RUN_CONTEXT.runner.io_manager.wait_writable(fd)
@@ -66,6 +110,30 @@ async def wait_writable(fd: (int | _HasFileNo)) -> None:
 
 
 def notify_closing(fd: (int | _HasFileNo)) -> None:
+    """Notify waiters of the given object that it will be closed.
+
+    Call this before closing a file descriptor (on Unix) or socket (on
+    Windows). This will cause any `wait_readable` or `wait_writable`
+    calls on the given object to immediately wake up and raise
+    `~trio.ClosedResourceError`.
+
+    This doesn't actually close the object – you still have to do that
+    yourself afterwards. Also, you want to be careful to make sure no
+    new tasks start waiting on the object in between when you call this
+    and when it's actually closed. So to close something properly, you
+    usually want to do these steps in order:
+
+    1. Explicitly mark the object as closed, so that any new attempts
+       to use it will abort before they start.
+    2. Call `notify_closing` to wake up any already-existing users.
+    3. Actually close the object.
+
+    It's also possible to do them in a different order if that's more
+    convenient, *but only if* you make sure not to have any checkpoints in
+    between the steps. This way they all happen in a single atomic
+    step, so other tasks won't be able to tell what order they happened
+    in anyway.
+    """
     locals()[LOCALS_KEY_KI_PROTECTION_ENABLED] = True
     try:
         return GLOBAL_RUN_CONTEXT.runner.io_manager.notify_closing(fd)

src/trio/_core/_generated_io_windows.py

@@ -20,6 +20,27 @@
 
 
 async def wait_readable(sock: (_HasFileNo | int)) -> None:
+    """Block until the kernel reports that the given object is readable.
+
+    On Unix systems, ``sock`` must either be an integer file descriptor,
+    or else an object with a ``.fileno()`` method which returns an
+    integer file descriptor. Any kind of file descriptor can be passed,
+    though the exact semantics will depend on your kernel. For example,
+    this probably won't do anything useful for on-disk files.
+
+    On Windows systems, ``sock`` must either be an integer ``SOCKET``
+    handle, or else an object with a ``.fileno()`` method which returns
+    an integer ``SOCKET`` handle. File descriptors aren't supported,
+    and neither are handles that refer to anything besides a
+    ``SOCKET``.
+
+    :raises trio.BusyResourceError:
+        if another task is already waiting for the given socket to
+        become readable.
+    :raises trio.ClosedResourceError:
+        if another task calls :func:`notify_closing` while this
+        function is still working.
+    """
     locals()[LOCALS_KEY_KI_PROTECTION_ENABLED] = True
     try:
         return await GLOBAL_RUN_CONTEXT.runner.io_manager.wait_readable(sock)
@@ -28,6 +49,17 @@ async def wait_readable(sock: (_HasFileNo | int)) -> None:
 
 
 async def wait_writable(sock: (_HasFileNo | int)) -> None:
+    """Block until the kernel reports that the given object is writable.
+
+    See `wait_readable` for the definition of ``sock``.
+
+    :raises trio.BusyResourceError:
+        if another task is already waiting for the given socket to
+        become writable.
+    :raises trio.ClosedResourceError:
+        if another task calls :func:`notify_closing` while this
+        function is still working.
+    """
     locals()[LOCALS_KEY_KI_PROTECTION_ENABLED] = True
     try:
         return await GLOBAL_RUN_CONTEXT.runner.io_manager.wait_writable(sock)
@@ -36,6 +68,30 @@ async def wait_writable(sock: (_HasFileNo | int)) -> None:
 
 
 def notify_closing(handle: (Handle | int | _HasFileNo)) -> None:
+    """Notify waiters of the given object that it will be closed.
+
+    Call this before closing a file descriptor (on Unix) or socket (on
+    Windows). This will cause any `wait_readable` or `wait_writable`
+    calls on the given object to immediately wake up and raise
+    `~trio.ClosedResourceError`.
+
+    This doesn't actually close the object – you still have to do that
+    yourself afterwards. Also, you want to be careful to make sure no
+    new tasks start waiting on the object in between when you call this
+    and when it's actually closed. So to close something properly, you
+    usually want to do these steps in order:
+
+    1. Explicitly mark the object as closed, so that any new attempts
+       to use it will abort before they start.
+    2. Call `notify_closing` to wake up any already-existing users.
+    3. Actually close the object.
+
+    It's also possible to do them in a different order if that's more
+    convenient, *but only if* you make sure not to have any checkpoints in
+    between the steps. This way they all happen in a single atomic
+    step, so other tasks won't be able to tell what order they happened
+    in anyway.
+    """
     locals()[LOCALS_KEY_KI_PROTECTION_ENABLED] = True
     try:
         return GLOBAL_RUN_CONTEXT.runner.io_manager.notify_closing(handle)
@@ -44,6 +100,11 @@ def notify_closing(handle: (Handle | int | _HasFileNo)) -> None:
 
 
 def register_with_iocp(handle: (int | CData)) -> None:
+    """TODO: these are implemented, but are currently more of a sketch than
+    anything real. See `#26
+    <https://github.com/python-trio/trio/issues/26>`__ and `#52
+    <https://github.com/python-trio/trio/issues/52>`__.
+    """
     locals()[LOCALS_KEY_KI_PROTECTION_ENABLED] = True
     try:
         return GLOBAL_RUN_CONTEXT.runner.io_manager.register_with_iocp(handle)
@@ -54,6 +115,11 @@ def register_with_iocp(handle: (int | CData)) -> None:
 async def wait_overlapped(
     handle_: (int | CData), lpOverlapped: (CData | int)
 ) -> object:
+    """TODO: these are implemented, but are currently more of a sketch than
+    anything real. See `#26
+    <https://github.com/python-trio/trio/issues/26>`__ and `#52
+    <https://github.com/python-trio/trio/issues/52>`__.
+    """
     locals()[LOCALS_KEY_KI_PROTECTION_ENABLED] = True
     try:
         return await GLOBAL_RUN_CONTEXT.runner.io_manager.wait_overlapped(
@@ -66,6 +132,11 @@ async def wait_overlapped(
 async def write_overlapped(
     handle: (int | CData), data: Buffer, file_offset: int = 0
 ) -> int:
+    """TODO: these are implemented, but are currently more of a sketch than
+    anything real. See `#26
+    <https://github.com/python-trio/trio/issues/26>`__ and `#52
+    <https://github.com/python-trio/trio/issues/52>`__.
+    """
     locals()[LOCALS_KEY_KI_PROTECTION_ENABLED] = True
     try:
         return await GLOBAL_RUN_CONTEXT.runner.io_manager.write_overlapped(
@@ -78,6 +149,11 @@ async def write_overlapped(
 async def readinto_overlapped(
     handle: (int | CData), buffer: Buffer, file_offset: int = 0
 ) -> int:
+    """TODO: these are implemented, but are currently more of a sketch than
+    anything real. See `#26
+    <https://github.com/python-trio/trio/issues/26>`__ and `#52
+    <https://github.com/python-trio/trio/issues/52>`__.
+    """
     locals()[LOCALS_KEY_KI_PROTECTION_ENABLED] = True
     try:
         return await GLOBAL_RUN_CONTEXT.runner.io_manager.readinto_overlapped(
@@ -88,6 +164,11 @@ async def readinto_overlapped(
 
 
 def current_iocp() -> int:
+    """TODO: these are implemented, but are currently more of a sketch than
+    anything real. See `#26
+    <https://github.com/python-trio/trio/issues/26>`__ and `#52
+    <https://github.com/python-trio/trio/issues/52>`__.
+    """
     locals()[LOCALS_KEY_KI_PROTECTION_ENABLED] = True
     try:
         return GLOBAL_RUN_CONTEXT.runner.io_manager.current_iocp()
@@ -96,6 +177,11 @@ def current_iocp() -> int:
 
 
 def monitor_completion_key() -> ContextManager[tuple[int, UnboundedQueue[object]]]:
+    """TODO: these are implemented, but are currently more of a sketch than
+    anything real. See `#26
+    <https://github.com/python-trio/trio/issues/26>`__ and `#52
+    <https://github.com/python-trio/trio/issues/52>`__.
+    """
     locals()[LOCALS_KEY_KI_PROTECTION_ENABLED] = True
     try:
         return GLOBAL_RUN_CONTEXT.runner.io_manager.monitor_completion_key()