Add more documentation

Author: notgull

src/os/unix.rs

@@ -4,6 +4,40 @@
 use std::os::unix::io::BorrowedFd;
 
 /// Get a file descriptor that can be used to wait for readiness in an external runtime.
+///
+/// This file descriptor is equivalent to the one used by the underlying epoll/kqueue/event ports
+/// instance for polling. The intention is that this file descriptor can be registered into an
+/// external runtime (like [`calloop`] or GLib) so that `async-io` can be seamlessly polled
+/// alongside the other runtime.
+///
+/// Not every backend used on `unix` has an associated file descriptor, however. While epoll,
+/// kqueue and event ports have a file descriptor as a backend, on some Unix systems `async-io`
+/// will use the `poll()` system call instead. Since there are no file descriptors intrinsically
+/// associated with `poll()`, this function will return `None`.
+///
+/// There is presently no way to stop the "`async-io`" thread from being launched, so the reactor
+/// will still be continiously polled on that thread. This fact should be kept in mind by anyone
+/// looking to integrate `async-io` into another runtime using this function.
+///
+/// It is possible to use this function to call raw system calls on the underlying event source.
+/// This is generally not recommended, since registered event sources may conflict with `async-io`'s
+/// existing scheme for managing sources. The behavior resulting from this is not specified, but
+/// will not result in undefined behavior. This could include panics, incorrect results, aborts,
+/// memory leaks, and non-termination.
+///
+/// ## Example
+///
+/// ```
+/// #![cfg(unix)]
+///
+/// use async_io::os::unix::reactor_fd;
+///
+/// my_runtime::register(reactor_fd());
+/// # mod my_runtime {
+/// #     use std::os::unix::io::BorrowedFd;
+/// #     fn register(_: BorrowedFd<'_>) {}
+/// # }
+/// ```
 #[cfg(not(async_io_no_io_safety))]
 pub fn reactor_fd() -> Option<BorrowedFd<'static>> {
     cfg_if::cfg_if! {