diff --git a/libc/include/sys/select.h b/libc/include/sys/select.h
index 9be444c..1ee8d2a 100644
--- a/libc/include/sys/select.h
+++ b/libc/include/sys/select.h
@@ -26,8 +26,12 @@
  * SUCH DAMAGE.
  */
 
-#ifndef _SYS_SELECT_H_
-#define _SYS_SELECT_H_
+#pragma once
+
+/**
+ * @file sys/select.h
+ * @brief Wait for events on a set of file descriptors (but use <poll.h> instead).
+ */
 
 #include <sys/cdefs.h>
 #include <sys/types.h>
@@ -39,9 +43,17 @@
 
 typedef unsigned long fd_mask;
 
+/**
+ * The limit on the largest fd that can be used with this API.
+ * Use <poll.h> instead.
+ */
 #define FD_SETSIZE 1024
 #define NFDBITS (8 * sizeof(fd_mask))
 
+/**
+ * The type of a file descriptor set. Limited to 1024 fds.
+ * Use <poll.h> instead.
+ */
 typedef struct {
   fd_mask fds_bits[FD_SETSIZE/NFDBITS];
 } fd_set;
@@ -67,21 +79,53 @@
 #define __FD_SET(fd, set) (__FDS_BITS(fd_set*,set)[__FDELT(fd)] |= __FDMASK(fd))
 #define __FD_ISSET(fd, set) ((__FDS_BITS(const fd_set*,set)[__FDELT(fd)] & __FDMASK(fd)) != 0)
 
-
 #if __ANDROID_API__ >= __ANDROID_API_L__
+
+/** Removes `fd` from the given set. Use <poll.h> instead. */
 #define FD_CLR(fd, set) __FD_CLR_chk(fd, set, __bos(set))
+/** Adds `fd` to the given set. Use <poll.h> instead. */
 #define FD_SET(fd, set) __FD_SET_chk(fd, set, __bos(set))
+/** Tests whether `fd` is in the given set. Use <poll.h> instead. */
 #define FD_ISSET(fd, set) __FD_ISSET_chk(fd, set, __bos(set))
+
 #else
+
+/** Removes `fd` from the given set. Use <poll.h> instead. */
 #define FD_CLR(fd, set) __FD_CLR(fd, set)
+/** Adds `fd` to the given set. Use <poll.h> instead. */
 #define FD_SET(fd, set) __FD_SET(fd, set)
+/** Tests whether `fd` is in the given set. Use <poll.h> instead. */
 #define FD_ISSET(fd, set) __FD_ISSET(fd, set)
+
 #endif /* __ANDROID_API >= 21 */
 
+/**
+ * [select(2)](http://man7.org/linux/man-pages/man2/select.2.html) waits on a
+ * set of file descriptors. Use poll() instead.
+ *
+ * Returns the number of ready file descriptors on success, 0 for timeout,
+ * and returns -1 and sets `errno` on failure.
+ */
 int select(int __fd_count, fd_set* __read_fds, fd_set* __write_fds, fd_set* __exception_fds, struct timeval* __timeout);
+
+/**
+ * [pselect(2)](http://man7.org/linux/man-pages/man2/select.2.html) waits on a
+ * set of file descriptors. Use ppoll() instead.
+ *
+ * Returns the number of ready file descriptors on success, 0 for timeout,
+ * and returns -1 and sets `errno` on failure.
+ */
 int pselect(int __fd_count, fd_set* __read_fds, fd_set* __write_fds, fd_set* __exception_fds, const struct timespec* __timeout, const sigset_t* __mask);
+
+/**
+ * [pselect64(2)](http://man7.org/linux/man-pages/man2/select.2.html) waits on a
+ * set of file descriptors. Use ppoll64() instead.
+ *
+ * Returns the number of ready file descriptors on success, 0 for timeout,
+ * and returns -1 and sets `errno` on failure.
+ *
+ * Available since API level 28.
+ */
 int pselect64(int __fd_count, fd_set* __read_fds, fd_set* __write_fds, fd_set* __exception_fds, const struct timespec* __timeout, const sigset64_t* __mask) __INTRODUCED_IN(28);
 
 __END_DECLS
-
-#endif