Merge "Another round of documentation."

48 files changed, 908 insertions, 262 deletions

diff --git a/libc/include/android/set_abort_message.h b/libc/include/android/set_abort_message.h
index 3dde67360..5d8d8eeed 100644
--- a/libc/include/android/set_abort_message.h
+++ b/libc/include/android/set_abort_message.h
@@ -26,15 +26,26 @@
  * SUCH DAMAGE.
  */
 
-#ifndef _SET_ABORT_MESSAGE_H
-#define _SET_ABORT_MESSAGE_H
+#pragma once
+
+/**
+ * @file android/set_abort_message.h
+ * @brief The android_set_abort_message() function.
+ */
 
 #include <sys/cdefs.h>
 
 __BEGIN_DECLS
 
+/**
+ * android_set_abort_message() sets the abort message that will be shown
+ * by [debuggerd](https://source.android.com/devices/tech/debug/native-crash).
+ * This is meant for use by libraries that deliberately abort so that they can
+ * provide an explanation. It is used within bionic to implement assert() and
+ * all FORTIFY/fdsan aborts.
+ *
+ * Available since API level 21.
+ */
 void android_set_abort_message(const char* __msg) __INTRODUCED_IN(21);
 
 __END_DECLS
-
-#endif
diff --git a/libc/include/bits/auxvec.h b/libc/include/bits/auxvec.h
index de3cfbb33..4d394776a 100644
--- a/libc/include/bits/auxvec.h
+++ b/libc/include/bits/auxvec.h
@@ -26,18 +26,24 @@
  * SUCH DAMAGE.
  */
 
-#ifndef _BITS_AUXVEC_H_
-#define _BITS_AUXVEC_H_
+#pragma once
+
+/**
+ * @file bits/auxvec.h
+ * @brief Constants for use with getauxval().
+ */
 
 #include <sys/cdefs.h>
 
 #include <linux/auxvec.h>
 
-/* Historical arch-specific cruft. */
-#define AT_FPUCW 18 /* SuperH */
-#define AT_DCACHEBSIZE 19 /* PowerPC */
-#define AT_ICACHEBSIZE 20 /* PowerPC */
-#define AT_UCACHEBSIZE 21 /* PowerPC */
-#define AT_IGNOREPPC 22 /* PowerPC */
-
-#endif
+/** Historical SuperH cruft. Irrelevant on Android. */
+#define AT_FPUCW 18
+/** Historical PowerPC cruft. Irrelevant on Android. */
+#define AT_DCACHEBSIZE 19
+/** Historical PowerPC cruft. Irrelevant on Android. */
+#define AT_ICACHEBSIZE 20
+/** Historical PowerPC cruft. Irrelevant on Android. */
+#define AT_UCACHEBSIZE 21
+/** Historical PowerPC cruft. Irrelevant on Android. */
+#define AT_IGNOREPPC 22
diff --git a/libc/include/bits/epoll_event.h b/libc/include/bits/epoll_event.h
index 054323cef..b2b4c8715 100644
--- a/libc/include/bits/epoll_event.h
+++ b/libc/include/bits/epoll_event.h
@@ -26,12 +26,17 @@
  * SUCH DAMAGE.
  */
 
-#ifndef _BITS_EPOLL_EVENT_H_
-#define _BITS_EPOLL_EVENT_H_
+#pragma once
+
+/**
+ * @file bits/epoll_event.h
+ * @brief Types for epoll().
+ */
 
 #include <sys/cdefs.h>
 #include <stdint.h>
 
+/** The union of possible data types for an `epoll_event`. */
 typedef union epoll_data {
   void* ptr;
   int fd;
@@ -39,6 +44,7 @@ typedef union epoll_data {
   uint64_t u64;
 } epoll_data_t;
 
+/** The type representing an epoll() event. */
 struct epoll_event {
   uint32_t events;
   epoll_data_t data;
@@ -47,5 +53,3 @@ struct epoll_event {
 __packed
 #endif
 ;
-
-#endif
diff --git a/libc/include/bits/fcntl.h b/libc/include/bits/fcntl.h
index e3b0e8cdc..597aa6ee7 100644
--- a/libc/include/bits/fcntl.h
+++ b/libc/include/bits/fcntl.h
@@ -26,15 +26,23 @@
  * SUCH DAMAGE.
  */
 
-#ifndef _BITS_FCNTL_H_
-#define _BITS_FCNTL_H_
+#pragma once
+
+/**
+ * @file bits/fcntl.h
+ * @brief The fcntl() function.
+ */
 
 #include <sys/cdefs.h>
 
 __BEGIN_DECLS
 
+/**
+ * [fcntl(3)](http://man7.org/linux/man-pages/man2/fcntl.2.html) performs various operations
+ * on file descriptors.
+ *
+ * The return value depends on the operation.
+ */
 int fcntl(int __fd, int __cmd, ...);
 
 __END_DECLS
-
-#endif
diff --git a/libc/include/bits/getopt.h b/libc/include/bits/getopt.h
index 548144995..0411716a6 100644
--- a/libc/include/bits/getopt.h
+++ b/libc/include/bits/getopt.h
@@ -26,18 +26,42 @@
  * SUCH DAMAGE.
  */
 
-#ifndef _BITS_GETOPT_H_
-#define _BITS_GETOPT_H_
+#pragma once
 
 #include <sys/cdefs.h>
 
 __BEGIN_DECLS
 
+/**
+ * [getopt(3)](http://man7.org/linux/man-pages/man3/getopt.3.html) parses command-line options.
+ *
+ * Returns the next option character on success, returns -1 if all options have been parsed, and
+ * returns `'?'` on error.
+ */
 int getopt(int __argc, char* const __argv[], const char* __options);
 
+/**
+ * Points to the text of the corresponding value for options that take an argument.
+ */
 extern char* optarg;
-extern int optind, opterr, optopt;
 
-__END_DECLS
+/**
+ * The index of the next element to be processed.
+ * On Android, callers should set `optreset = 1` rather than trying to reset `optind` to
+ * scan a new argument vector.
+ */
+extern int optind;
 
-#endif
+/**
+ * Determines whether getopt() outputs error messages.
+ * Callers should set this to `0` to disable error messages.
+ * Defaults to non-zero.
+ */
+extern int opterr;
+
+/**
+ * The last unrecognized option character, valid when getopt() returns `'?'`.
+ */
+extern int optopt;
+
+__END_DECLS
diff --git a/libc/include/bits/in_addr.h b/libc/include/bits/in_addr.h
index 834c056ea..30eb04b66 100644
--- a/libc/include/bits/in_addr.h
+++ b/libc/include/bits/in_addr.h
@@ -26,16 +26,20 @@
  * SUCH DAMAGE.
  */
 
-#ifndef _BITS_IN_ADDR_H_
-#define _BITS_IN_ADDR_H_
+#pragma once
+
+/**
+ * @file bits/in_addr.h
+ * @brief IPv4 address types.
+ */
 
 #include <sys/cdefs.h>
 #include <stdint.h>
 
+/** An integral type representing an IPv4 address. */
 typedef uint32_t in_addr_t;
 
+/** A structure representing an IPv4 address. */
 struct in_addr {
   in_addr_t s_addr;
 };
-
-#endif
diff --git a/libc/include/bits/ioctl.h b/libc/include/bits/ioctl.h
index 745bbf03a..9ed12926c 100644
--- a/libc/include/bits/ioctl.h
+++ b/libc/include/bits/ioctl.h
@@ -26,13 +26,20 @@
  * SUCH DAMAGE.
  */
 
-#ifndef _BITS_IOCTL_H_
-#define _BITS_IOCTL_H_
+#pragma once
+
+/**
+ * @file bits/ioctl.h
+ * @brief The ioctl() function.
+ */
 
 #include <sys/cdefs.h>
 
 __BEGIN_DECLS
 
+/**
+ * [ioctl(2)](http://man7.org/linux/man-pages/man2/ioctl.2.html) operates on device files.
+ */
 int ioctl(int __fd, int __request, ...);
 
 /*
@@ -57,5 +64,3 @@ int ioctl(int __fd, unsigned __request, ...) __overloadable __enable_if(1, "") _
 #endif
 
 __END_DECLS
-
-#endif
diff --git a/libc/include/bits/ip_mreq_source.h b/libc/include/bits/ip_mreq_source.h
index 0eb8d688c..83490a4fa 100644
--- a/libc/include/bits/ip_mreq_source.h
+++ b/libc/include/bits/ip_mreq_source.h
@@ -26,16 +26,21 @@
  * SUCH DAMAGE.
  */
 
-#ifndef _BITS_IP_MREQ_SOURCE_H_
-#define _BITS_IP_MREQ_SOURCE_H_
+#pragma once
+
+/**
+ * @file bits/ip_mreq_source.h
+ * @brief The `ip_mreq_source` type.
+ */
 
 #include <sys/cdefs.h>
 #include <bits/in_addr.h>
 
+/**
+ * The type representing an IPv4 multicast source.
+ */
 struct ip_mreq_source {
   struct in_addr imr_multiaddr;
   struct in_addr imr_interface;
   struct in_addr imr_sourceaddr;
 };
-
-#endif
diff --git a/libc/include/bits/ip_msfilter.h b/libc/include/bits/ip_msfilter.h
index 23c127dbf..cb3350bdc 100644
--- a/libc/include/bits/ip_msfilter.h
+++ b/libc/include/bits/ip_msfilter.h
@@ -26,12 +26,17 @@
  * SUCH DAMAGE.
  */
 
-#ifndef _BITS_IP_MSFILTER_H_
-#define _BITS_IP_MSFILTER_H_
+#pragma once
+
+/**
+ * @file bits/ip_msfilter.h
+ * @brief IPv4 multicast filtering.
+ */
 
 #include <sys/cdefs.h>
 #include <bits/in_addr.h>
 
+/** The type representing an IPv4 multicast filter. */
 struct ip_msfilter {
   struct in_addr imsf_multiaddr;
   struct in_addr imsf_interface;
@@ -39,5 +44,3 @@ struct ip_msfilter {
   uint32_t imsf_numsrc;
   struct in_addr imsf_slist[1];
 };
-
-#endif
diff --git a/libc/include/bits/lockf.h b/libc/include/bits/lockf.h
index 929c68c7f..58ab03113 100644
--- a/libc/include/bits/lockf.h
+++ b/libc/include/bits/lockf.h
@@ -26,22 +26,42 @@
  * SUCH DAMAGE.
  */
 
-#ifndef _BITS_LOCKF_H_
-#define _BITS_LOCKF_H_
+#pragma once
+
+/**
+ * @file bits/lockf.h
+ * @brief The lockf() function.
+ */
 
 #include <sys/cdefs.h>
 #include <sys/types.h>
 
+/** lockf() command to unlock a section of a file. */
 #define F_ULOCK 0
+/** lockf() command to block until it locks a section of a file. */
 #define F_LOCK 1
+/** lockf() command to try to lock a section of a file. */
 #define F_TLOCK 2
+/** lockf() command to test whether a section of a file is unlocked (or locked by the caller). */
 #define F_TEST 3
 
 __BEGIN_DECLS
 
+/**
+ * [lockf(3)](http://man7.org/linux/man-pages/man3/lockf.3.html) manipulates POSIX file locks.
+ *
+ * Returns 0 on success, and returns -1 and sets `errno` on failure.
+ *
+ * Available since API level 24.
+ *
+ * See also flock().
+ */
 int lockf(int __fd, int __cmd, off_t __length) __RENAME_IF_FILE_OFFSET64(lockf64) __INTRODUCED_IN(24);
+
+/**
+ * Like lockf() but allows using a 64-bit length
+ * even from a 32-bit process without `__FILE_OFFSET_BITS=64`.
+ */
 int lockf64(int __fd, int __cmd, off64_t __length) __INTRODUCED_IN(24);
 
 __END_DECLS
-
-#endif
diff --git a/libc/include/bits/mbstate_t.h b/libc/include/bits/mbstate_t.h
index 057a2c99c..0f9323d1b 100644
--- a/libc/include/bits/mbstate_t.h
+++ b/libc/include/bits/mbstate_t.h
@@ -26,16 +26,22 @@
  * SUCH DAMAGE.
  */
 
-#ifndef _BITS_MBSTATE_T_H_
-#define _BITS_MBSTATE_T_H_
+#pragma once
+
+/**
+ * @file bits/mbstate_t.h
+ * @brief The `mbstate_t` type.
+ */
 
 #include <sys/cdefs.h>
 
+/**
+ * An opaque type used by the multibyte conversion functions.
+ * Do not make assumptions about the content of this type.
+ */
 typedef struct {
   unsigned char __seq[4];
 #ifdef __LP64__
   unsigned char __reserved[4];
 #endif
 } mbstate_t;
-
-#endif
diff --git a/libc/include/bits/sa_family_t.h b/libc/include/bits/sa_family_t.h
index 98ca27f18..df8b695c0 100644
--- a/libc/include/bits/sa_family_t.h
+++ b/libc/include/bits/sa_family_t.h
@@ -26,11 +26,14 @@
  * SUCH DAMAGE.
  */
 
-#ifndef _BITS_SA_FAMILY_T_H_
-#define _BITS_SA_FAMILY_T_H_
+#pragma once
+
+/**
+ * @file bits/sa_family_t.h
+ * @brief The `sa_family_t` type.
+ */
 
 #include <sys/cdefs.h>
 
+/** The type of fields like `sa_family`. */
 typedef unsigned short sa_family_t;
-
-#endif
diff --git a/libc/include/bits/seek_constants.h b/libc/include/bits/seek_constants.h
index 34c5866c6..6b8860689 100644
--- a/libc/include/bits/seek_constants.h
+++ b/libc/include/bits/seek_constants.h
@@ -26,11 +26,16 @@
  * SUCH DAMAGE.
  */
 
-#ifndef _BITS_SEEK_CONSTANTS_H_
-#define _BITS_SEEK_CONSTANTS_H_
+#pragma once
 
+/**
+ * @file bits/seek_constants.h
+ * @brief The `SEEK_` constants.
+ */
+
+/** Seek to an absolute offset. */
 #define SEEK_SET 0
+/** Seek relative to the current offset. */
 #define SEEK_CUR 1
+/** Seek relative to the end of the file. */
 #define SEEK_END 2
-
-#endif
diff --git a/libc/include/bits/strcasecmp.h b/libc/include/bits/strcasecmp.h
index 594046a24..3994b6893 100644
--- a/libc/include/bits/strcasecmp.h
+++ b/libc/include/bits/strcasecmp.h
@@ -26,8 +26,12 @@
  * SUCH DAMAGE.
  */
 
-#ifndef _BITS_STRCASECMP_H_
-#define _BITS_STRCASECMP_H_
+#pragma once
+
+/**
+ * @file bits/strcasecmp.h
+ * @brief Case-insensitive string comparison.
+ */
 
 #include <sys/cdefs.h>
 #include <sys/types.h>
@@ -35,11 +39,33 @@
 
 __BEGIN_DECLS
 
+/**
+ * [strcasecmp(3)](http://man7.org/linux/man-pages/man3/strcasecmp.3.html) compares two strings
+ * ignoring case.
+ *
+ * Returns an integer less than, equal to, or greater than zero if the first string is less than,
+ * equal to, or greater than the second string (ignoring case).
+ */
 int strcasecmp(const char* __s1, const char* __s2) __attribute_pure__;
+
+/**
+ * Like strcasecmp() but taking a `locale_t`.
+ */
 int strcasecmp_l(const char* __s1, const char* __s2, locale_t __l) __attribute_pure__ __INTRODUCED_IN(23);
+
+/**
+ * [strncasecmp(3)](http://man7.org/linux/man-pages/man3/strncasecmp.3.html) compares the first
+ * `n` bytes of two strings ignoring case.
+ *
+ * Returns an integer less than, equal to, or greater than zero if the first `n` bytes of the
+ * first string is less than, equal to, or greater than the first `n` bytes of the second
+ * string (ignoring case).
+ */
 int strncasecmp(const char* __s1, const char* __s2, size_t __n) __attribute_pure__;
+
+/**
+ * Like strncasecmp() but taking a `locale_t`.
+ */
 int strncasecmp_l(const char* __s1, const char* __s2, size_t __n, locale_t __l) __attribute_pure__ __INTRODUCED_IN(23);
 
 __END_DECLS
-
-#endif
diff --git a/libc/include/bits/struct_file.h b/libc/include/bits/struct_file.h
index 08e18a13a..abbd32028 100644
--- a/libc/include/bits/struct_file.h
+++ b/libc/include/bits/struct_file.h
@@ -26,13 +26,13 @@
  * SUCH DAMAGE.
  */
 
-#ifndef BITS_FILE_H
-#define BITS_FILE_H
+#pragma once
 
 #include <sys/cdefs.h>
 
 __BEGIN_DECLS
 
+/** The opaque structure implementing `FILE`. Do not make any assumptions about its content. */
 struct __sFILE {
 #if defined(__LP64__)
   char __private[152];
@@ -42,5 +42,3 @@ struct __sFILE {
 } __attribute__((aligned(sizeof(void*))));
 
 __END_DECLS
-
-#endif /* BITS_FILE_H */
diff --git a/libc/include/bits/timespec.h b/libc/include/bits/timespec.h
index df7a7ce4d..0497cfe1f 100644
--- a/libc/include/bits/timespec.h
+++ b/libc/include/bits/timespec.h
@@ -26,8 +26,12 @@
  * SUCH DAMAGE.
  */
 
-#ifndef _BITS_TIMESPEC_H_
-#define _BITS_TIMESPEC_H_
+#pragma once
+
+/**
+ * @file bits/timespec.h
+ * @brief The `timespec` struct.
+ */
 
 #include <sys/cdefs.h>
 #include <sys/types.h>
@@ -38,10 +42,11 @@
  */
 #ifndef _STRUCT_TIMESPEC
 #define _STRUCT_TIMESPEC
+/** Represents a time. */
 struct timespec {
+  /** Number of seconds. */
   time_t tv_sec;
+  /** Number of nanoseconds. Must be less than 1,000,000. */
   long tv_nsec;
 };
 #endif
-
-#endif
diff --git a/libc/include/bits/wait.h b/libc/include/bits/wait.h
index a35f789ae..a6a212904 100644
--- a/libc/include/bits/wait.h
+++ b/libc/include/bits/wait.h
@@ -26,24 +26,43 @@
  * SUCH DAMAGE.
  */
 
-#ifndef _BITS_WAIT_H_
-#define _BITS_WAIT_H_
+#pragma once
+
+/**
+ * @file bits/wait.h
+ * @brief Process exit status macros.
+ */
 
 #include <sys/cdefs.h>
 
 #include <linux/wait.h>
 
-#define WEXITSTATUS(s) (((s) & 0xff00) >> 8)
-#define WCOREDUMP(s)   ((s) & 0x80)
-#define WTERMSIG(s)    ((s) & 0x7f)
-#define WSTOPSIG(s)    WEXITSTATUS(s)
+/** Returns the exit status from a process for which `WIFEXITED` is true. */
+#define WEXITSTATUS(__status) (((__status) & 0xff00) >> 8)
+
+/** Returns true if a process dumped core. */
+#define WCOREDUMP(__status) ((__status) & 0x80)
+
+/** Returns the terminating signal from a process, or 0 if it exited normally. */
+#define WTERMSIG(__status) ((__status) & 0x7f)
+
+/** Returns the signal that stopped the process, if `WIFSTOPPED` is true. */
+#define WSTOPSIG(__status) WEXITSTATUS(__status)
+
+/** Returns true if the process exited normally. */
+#define WIFEXITED(__status) (WTERMSIG(__status) == 0)
+
+/** Returns true if the process was stopped by a signal. */
+#define WIFSTOPPED(__status) (WTERMSIG(__status) == 0x7f)
+
+/** Returns true if the process was terminated by a signal. */
+#define WIFSIGNALED(__status) (WTERMSIG((__status)+1) >= 2)
 
-#define WIFEXITED(s)    (WTERMSIG(s) == 0)
-#define WIFSTOPPED(s)   (WTERMSIG(s) == 0x7f)
-#define WIFSIGNALED(s)  (WTERMSIG((s)+1) >= 2)
-#define WIFCONTINUED(s) ((s) == 0xffff)
+/** Returns true if the process was resumed . */
+#define WIFCONTINUED(__status) ((__status) == 0xffff)
 
-#define W_EXITCODE(ret, sig) ((ret) << 8 | (sig))
-#define W_STOPCODE(sig)      ((sig) << 8 | 0x7f)
+/** Constructs a status value from the given exit code and signal number. */
+#define W_EXITCODE(__exit_code, __signal_number) ((__exit_code) << 8 | (__signal_number))
 
-#endif
+/** Constructs a status value for a process stopped by the given signal. */
+#define W_STOPCODE(__signal_number) ((__signal_number) << 8 | 0x7f)
diff --git a/libc/include/bits/wchar_limits.h b/libc/include/bits/wchar_limits.h
index ffad6041f..311b02e3b 100644
--- a/libc/include/bits/wchar_limits.h
+++ b/libc/include/bits/wchar_limits.h
@@ -26,19 +26,23 @@
  * SUCH DAMAGE.
  */
 
-#ifndef _BITS_WCHAR_LIMITS_H_
-#define _BITS_WCHAR_LIMITS_H_
+#pragma once
+
+/**
+ * @file bits/wchar_limits.h
+ * @brief `wchar_t` limits.
+ */
 
 #include <sys/cdefs.h>
 
-/* Both GCC and clang define __WCHAR_MAX__. */
+/** The maximum value of a `wchar_t`. */
 #define WCHAR_MAX __WCHAR_MAX__
 
 /* As of 3.4, clang still doesn't define __WCHAR_MIN__. */
 #if defined(__WCHAR_UNSIGNED__)
+/** The minimum value of a `wchar_t`. */
 #  define WCHAR_MIN L'\0'
 #else
+/** The minimum value of a `wchar_t`. */
 #  define WCHAR_MIN (-(WCHAR_MAX) - 1)
 #endif
-
-#endif
diff --git a/libc/include/ctype.h b/libc/include/ctype.h
index df11cb13f..e91b0e25f 100644
--- a/libc/include/ctype.h
+++ b/libc/include/ctype.h
@@ -37,69 +37,129 @@
  *	@(#)ctype.h	5.3 (Berkeley) 4/3/91
  */
 
-#ifndef _CTYPE_H_
-#define _CTYPE_H_
+#pragma once
+
+/**
+ * @file ctype.h
+ * @brief ASCII character classification.
+ */
 
 #include <sys/cdefs.h>
 #include <xlocale.h>
 
+/** Internal implementation detail. Do not use. */
 #define _CTYPE_U 0x01
+/** Internal implementation detail. Do not use. */
 #define _CTYPE_L 0x02
+/** Internal implementation detail. Do not use. */
 #define _CTYPE_D 0x04
+/** Internal implementation detail. Do not use. */
 #define _CTYPE_S 0x08
+/** Internal implementation detail. Do not use. */
 #define _CTYPE_P 0x10
+/** Internal implementation detail. Do not use. */
 #define _CTYPE_C 0x20
+/** Internal implementation detail. Do not use. */
 #define _CTYPE_X 0x40
+/** Internal implementation detail. Do not use. */
 #define _CTYPE_B 0x80
+/** Internal implementation detail. Do not use. */
 #define _CTYPE_R (_CTYPE_P|_CTYPE_U|_CTYPE_L|_CTYPE_D|_CTYPE_B)
+/** Internal implementation detail. Do not use. */
 #define _CTYPE_A (_CTYPE_L|_CTYPE_U)
-
-/* _CTYPE_N was added to NDK r10 and is expected by gnu-libstdc++ */
+/** Internal implementation detail. Do not use. */
 #define _CTYPE_N _CTYPE_D
 
 __BEGIN_DECLS
 
+/** Internal implementation detail. Do not use. */
 extern const char* _ctype_;
 
+/** Returns true if `ch` is in `[A-Za-z0-9]`. */
 int isalnum(int __ch);
+/** Returns true if `ch` is in `[A-Za-z]`. */
 int isalpha(int __ch);
+/** Returns true if `ch` is a space or tab. */
 int isblank(int __ch);
+/** Returns true if `ch` is a control character (any character before space, plus DEL). */
 int iscntrl(int __ch);
+/** Returns true if `ch` is in `[0-9]`. */
 int isdigit(int __ch);
+/** Returns true if `ch` is `[A-Za-z0-9]` or punctuation. */
 int isgraph(int __ch);
+/** Returns true if `ch` is in `[a-z]`. */
 int islower(int __ch);
+/** Returns true if `ch` is `[A-Za-z0-9]` or punctuation or space. */
 int isprint(int __ch);
+/** Returns true if `ch` is punctuation. */
 int ispunct(int __ch);
+/** Returns true if `ch` is in `[ \f\n\r\t\v]`. */
 int isspace(int __ch);
+/** Returns true if `ch` is in `[A-Z]`. */
 int isupper(int __ch);
+/** Returns true if `ch` is in `[0-9a-f]`. */
 int isxdigit(int __ch);
+
+/** Returns the corresponding lower-case character if `ch` is upper-case, or `ch` otherwise. */
 int tolower(int __ch);
+
+/**
+ * Returns the corresponding lower-case character if `ch` is upper-case, or undefined otherwise.
+ *
+ * Available since API level 21.
+ *
+ * Prefer tolower() instead.
+ */
+int _tolower(int __ch) __INTRODUCED_IN(21);
+
+/** Returns the corresponding upper-case character if `ch` is lower-case, or `ch` otherwise. */
 int toupper(int __ch);
 
+/**
+ * Returns the corresponding upper-case character if `ch` is lower-case, or undefined otherwise.
+ *
+ * Available since API level 21.
+ *
+ * Prefer toupper() instead.
+ */
+int _toupper(int __ch) __INTRODUCED_IN(21);
+
 #if __ANDROID_API__ >= __ANDROID_API_L__
+/** Like isalnum but with an ignored `locale_t`. */
 int isalnum_l(int __ch, locale_t __l) __INTRODUCED_IN(21);
+/** Like isalpha but with an ignored `locale_t`. */
 int isalpha_l(int __ch, locale_t __l) __INTRODUCED_IN(21);
+/** Like isblank but with an ignored `locale_t`. */
 int isblank_l(int __ch, locale_t __l) __INTRODUCED_IN(21);
+/** Like iscntrl but with an ignored `locale_t`. */
 int iscntrl_l(int __ch, locale_t __l) __INTRODUCED_IN(21);
+/** Like isdigit but with an ignored `locale_t`. */
 int isdigit_l(int __ch, locale_t __l) __INTRODUCED_IN(21);
+/** Like isgraph but with an ignored `locale_t`. */
 int isgraph_l(int __ch, locale_t __l) __INTRODUCED_IN(21);
+/** Like islower but with an ignored `locale_t`. */
 int islower_l(int __ch, locale_t __l) __INTRODUCED_IN(21);
+/** Like isprint but with an ignored `locale_t`. */
 int isprint_l(int __ch, locale_t __l) __INTRODUCED_IN(21);
+/** Like ispunct but with an ignored `locale_t`. */
 int ispunct_l(int __ch, locale_t __l) __INTRODUCED_IN(21);
+/** Like isspace but with an ignored `locale_t`. */
 int isspace_l(int __ch, locale_t __l) __INTRODUCED_IN(21);
+/** Like isupper but with an ignored `locale_t`. */
 int isupper_l(int __ch, locale_t __l) __INTRODUCED_IN(21);
+/** Like isxdigit but with an ignored `locale_t`. */
 int isxdigit_l(int __ch, locale_t __l) __INTRODUCED_IN(21);
+/** Like tolower but with an ignored `locale_t`. */
 int tolower_l(int __ch, locale_t __l) __INTRODUCED_IN(21);
+/** Like toupper but with an ignored `locale_t`. */
 int toupper_l(int __ch, locale_t __l) __INTRODUCED_IN(21);
 #else
 // Implemented as static inlines before 21.
 #endif
 
+/** Returns true if `ch` is less than 0x80. */
 int isascii(int __ch);
+/** Returns `ch & 0x7f`. */
 int toascii(int __ch);
-int _tolower(int __ch) __INTRODUCED_IN(21);
-int _toupper(int __ch) __INTRODUCED_IN(21);
 
 __END_DECLS
-
-#endif
diff --git a/libc/include/getopt.h b/libc/include/getopt.h
index c5a6106ba..014226a26 100644
--- a/libc/include/getopt.h
+++ b/libc/include/getopt.h
@@ -30,42 +30,58 @@
  * POSSIBILITY OF SUCH DAMAGE.
  */
 
-#ifndef _GETOPT_H_
-#define _GETOPT_H_
+#pragma once
+
+/**
+ * @file getopt.h
+ * @brief The getopt() and getopt_long() functions.
+ */
 
 #include <sys/cdefs.h>
 
 #include <bits/getopt.h>
 
-/*
- * GNU-like getopt_long()/getopt_long_only() with 4.4BSD optreset extension.
- */
-#define no_argument        0
-#define required_argument  1
-#define optional_argument  2
+/** A `has_arg` value for `struct option`. */
+#define no_argument 0
+/** A `has_arg` value for `struct option`. */
+#define required_argument 1
+/** A `has_arg` value for `struct option`. */
+#define optional_argument 2
 
 struct option {
-	/* name of long option */
-	const char *name;
-	/*
-	 * one of no_argument, required_argument, and optional_argument:
-	 * whether option takes an argument
-	 */
-	int has_arg;
-	/* if not NULL, set *flag to val when option found */
-	int *flag;
-	/* if flag not NULL, value to set *flag to; else return value */
-	int val;
+  /** Name of long option. */
+  const char *name;
+
+  /**
+   * One of `no_argument`, `required_argument`, or `optional_argument`.
+   */
+  int has_arg;
+
+  /** If not NULL, set `*flag` to val when option found. */
+  int* flag;
+
+  /** If `flag` not NULL, the value to assign to `*flag`; otherwise the return value. */
+  int val;
 };
 
 __BEGIN_DECLS
+
+/**
+ * [getopt_long(3)](http://man7.org/linux/man-pages/man3/getopt.3.html) parses command-line options.
+ */
 int getopt_long(int __argc, char* const* __argv, const char* __options, const struct option* __long_options, int* __long_index);
+
+/**
+ * [getopt_long_only(3)](http://man7.org/linux/man-pages/man3/getopt.3.html) parses command-line options.
+ */
 int getopt_long_only(int __argc, char* const* __argv, const char* __options, const struct option* __long_options, int* __long_index);
 
 #ifndef _OPTRESET_DECLARED
-#define	_OPTRESET_DECLARED
-extern int optreset;			/* getopt(3) external variable */
+#define _OPTRESET_DECLARED
+/**
+ * Must be set to 1 to reset the `getopt` functions before scanning a new argument vector.
+ */
+extern int optreset;
 #endif
+
 __END_DECLS
- 
-#endif
diff --git a/libc/include/net/route.h b/libc/include/net/route.h
index 9c53875c6..21cd80b6d 100644
--- a/libc/include/net/route.h
+++ b/libc/include/net/route.h
@@ -26,13 +26,10 @@
  * SUCH DAMAGE.
  */
 
-#ifndef _NET_ROUTE_H_
-#define _NET_ROUTE_H_
+#pragma once
 
 #include <sys/cdefs.h>
 #include <sys/socket.h>
 #include <linux/route.h>
 #include <linux/in6.h>
 #include <linux/ipv6_route.h>
-
-#endif
diff --git a/libc/include/netinet/ether.h b/libc/include/netinet/ether.h
index 3e6a4e355..6268a14ab 100644
--- a/libc/include/netinet/ether.h
+++ b/libc/include/netinet/ether.h
@@ -26,19 +26,56 @@
  * SUCH DAMAGE.
  */
 
-#ifndef _NETINET_ETHER_H_
-#define _NETINET_ETHER_H_ 1
+#pragma once
+
+/**
+ * @file netinet/ether.h
+ * @brief Ethernet (MAC) addresses.
+ */
 
 #include <sys/cdefs.h>
 #include <netinet/if_ether.h>
 
 __BEGIN_DECLS
 
+/**
+ * [ether_ntoa(3)](http://man7.org/linux/man-pages/man3/ether_ntoa.3.html) returns a string
+ * representation of the given Ethernet address.
+ *
+ * Returns a pointer to a static buffer.
+ *
+ * Available since API level 11.
+ */
 char* ether_ntoa(const struct ether_addr* __addr) __INTRODUCED_IN(11);
+
+/**
+ * [ether_ntoa_r(3)](http://man7.org/linux/man-pages/man3/ether_ntoa_r.3.html) returns a string
+ * representation of the given Ethernet address.
+ *
+ * Returns a pointer to the given buffer.
+ *
+ * Available since API level 11.
+ */
 char* ether_ntoa_r(const struct ether_addr* __addr, char* __buf) __INTRODUCED_IN(11);
+
+/**
+ * [ether_aton(3)](http://man7.org/linux/man-pages/man3/ether_aton.3.html) returns an `ether_addr`
+ * corresponding to the given Ethernet address string.
+ *
+ * Returns a pointer to a static buffer, or NULL if the given string isn't a valid MAC address.
+ *
+ * Available since API level 11.
+ */
 struct ether_addr* ether_aton(const char* __ascii) __INTRODUCED_IN(11);
+
+/**
+ * [ether_aton_r(3)](http://man7.org/linux/man-pages/man3/ether_aton_r.3.html) returns an
+ * `ether_addr` corresponding to the given Ethernet address string.
+ *
+ * Returns a pointer to the given buffer, or NULL if the given string isn't a valid MAC address.
+ *
+ * Available since API level 11.
+ */
 struct ether_addr* ether_aton_r(const char* __ascii, struct ether_addr* __addr) __INTRODUCED_IN(11);
 
 __END_DECLS
-
-#endif
diff --git a/libc/include/sys/auxv.h b/libc/include/sys/auxv.h
index 9251390d3..c6519400d 100644
--- a/libc/include/sys/auxv.h
+++ b/libc/include/sys/auxv.h
@@ -26,8 +26,12 @@
  * SUCH DAMAGE.
  */
 
-#ifndef _SYS_AUXV_H_
-#define _SYS_AUXV_H_
+#pragma once
+
+/**
+ * @file sys/auxv.h
+ * @brief The getauxval() function.
+ */
 
 #include <sys/cdefs.h>
 
@@ -35,8 +39,15 @@
 
 __BEGIN_DECLS
 
+/**
+ * [getauxval(3)](http://man7.org/linux/man-pages/man2/personality.2.html) returns values from
+ * the ELF auxiliary vector passed by the kernel.
+ *
+ * Returns the corresponding value on success,
+ * and returns 0 and sets `errno` to `ENOENT` on failure.
+ *
+ * Available since API level 18.
+ */
 unsigned long int getauxval(unsigned long int __type) __INTRODUCED_IN(18);
 
 __END_DECLS
-
-#endif
diff --git a/libc/include/sys/capability.h b/libc/include/sys/capability.h
index 637c84419..4cb698f06 100644
--- a/libc/include/sys/capability.h
+++ b/libc/include/sys/capability.h
@@ -26,17 +26,32 @@
  * SUCH DAMAGE.
  */
 
-#ifndef _BIONIC_SYS_CAPABILITY_H
-#define _BIONIC_SYS_CAPABILITY_H
+#pragma once
+
+/**
+ * @file sys/capability.h
+ * @brief Capabilities.
+ */
 
 #include <sys/cdefs.h>
 #include <linux/capability.h>
 
 __BEGIN_DECLS
 
+/**
+ * [capget(2)](http://man7.org/linux/man-pages/man2/capget.2.html) gets the calling
+ * thread's capabilities.
+ *
+ * Returns 0 on success, and returns -1 and sets `errno` on failure.
+ */
 int capget(cap_user_header_t __hdr_ptr, cap_user_data_t __data_ptr);
+
+/**
+ * [capset(2)](http://man7.org/linux/man-pages/man2/capset.2.html) sets the calling
+ * thread's capabilities.
+ *
+ * Returns 0 on success, and returns -1 and sets `errno` on failure.
+ */
 int capset(cap_user_header_t __hdr_ptr, const cap_user_data_t __data_ptr);
 
 __END_DECLS
-
-#endif
diff --git a/libc/include/sys/eventfd.h b/libc/include/sys/eventfd.h
index 3cfb5e7fa..85f9877ed 100644
--- a/libc/include/sys/eventfd.h
+++ b/libc/include/sys/eventfd.h
@@ -26,24 +26,48 @@
  * SUCH DAMAGE.
  */
 
-#ifndef _SYS_EVENTFD_H
-#define _SYS_EVENTFD_H
+#pragma once
+
+/**
+ * @file sys/eventfd.h
+ * @brief Event notification file descriptors.
+ */
 
 #include <sys/cdefs.h>
 #include <fcntl.h>
 
 __BEGIN_DECLS
 
+/** The eventfd() flag for a close-on-exec file descriptor. */
 #define EFD_CLOEXEC O_CLOEXEC
+/** The eventfd() flag for a non-blocking file descriptor. */
 #define EFD_NONBLOCK O_NONBLOCK
 
-typedef uint64_t eventfd_t;
-
+/**
+ * [eventfd(2)](http://man7.org/linux/man-pages/man2/eventfd.2.html) creates a file descriptor
+ * for event notification.
+ *
+ * Returns a new file descriptor on success, and returns -1 and sets `errno` on failure.
+ */
 int eventfd(unsigned int __initial_value, int __flags);
 
+/** The type used by eventfd_read() and eventfd_write(). */
+typedef uint64_t eventfd_t;
+
+/**
+ * [eventfd_read(3)](http://man7.org/linux/man-pages/man2/eventfd.2.html) is a convenience
+ * wrapper to read an `eventfd_t` from an eventfd file descriptor.
+ *
+ * Returns 0 on success, or returns -1 otherwise.
+ */
 int eventfd_read(int __fd, eventfd_t* __value);
+
+/**
+ * [eventfd_write(3)](http://man7.org/linux/man-pages/man2/eventfd.2.html) is a convenience
+ * wrapper to write an `eventfd_t` to an eventfd file descriptor.
+ *
+ * Returns 0 on success, or returns -1 otherwise.
+ */
 int eventfd_write(int __fd, eventfd_t __value);
 
 __END_DECLS
-
-#endif
diff --git a/libc/include/sys/file.h b/libc/include/sys/file.h
index a4200219f..ccdfeea52 100644
--- a/libc/include/sys/file.h
+++ b/libc/include/sys/file.h
@@ -26,8 +26,12 @@
  * SUCH DAMAGE.
  */
 
-#ifndef _SYS_FILE_H_
-#define _SYS_FILE_H_
+#pragma once
+
+/**
+ * @file sys/file.h
+ * @brief The flock() function.
+ */
 
 #include <sys/cdefs.h>
 #include <sys/types.h>
@@ -36,8 +40,12 @@
 
 __BEGIN_DECLS
 
+/**
+ * [flock(2)](http://man7.org/linux/man-pages/man2/flock.2.html) performs
+ * advisory file lock operations.
+ *
+ * Returns 0 on success, and returns -1 and sets `errno` on failure.
+ */
 int flock(int __fd, int __op);
 
 __END_DECLS
-
-#endif
diff --git a/libc/include/sys/fsuid.h b/libc/include/sys/fsuid.h
index bb7a58d5f..c1c8ebb52 100644
--- a/libc/include/sys/fsuid.h
+++ b/libc/include/sys/fsuid.h
@@ -26,17 +26,36 @@
  * SUCH DAMAGE.
  */
 
-#ifndef _SYS_FSUID_H_
-#define _SYS_FSUID_H_
+#pragma once
+
+/**
+ * @file sys/fsuid.h
+ * @brief Set UID/GID for filesystem checks.
+ */
 
 #include <sys/cdefs.h>
 #include <sys/types.h>
 
 __BEGIN_DECLS
 
+/**
+ * [setfsuid(2)](http://man7.org/linux/man-pages/man2/setfsuid.2.html) sets the UID used for
+ * filesystem checks.
+ *
+ * Returns the previous UID.
+ *
+ * Available since API level 21.
+ */
 int setfsuid(uid_t __uid) __INTRODUCED_IN(21);
+
+/**
+ * [setfsgid(2)](http://man7.org/linux/man-pages/man2/setfsgid.2.html) sets the GID used for
+ * filesystem checks.
+ *
+ * Returns the previous GID.
+ *
+ * Available since API level 21.
+ */
 int setfsgid(gid_t __gid) __INTRODUCED_IN(21);
 
 __END_DECLS
-
-#endif
diff --git a/libc/include/sys/ioctl.h b/libc/include/sys/ioctl.h
index b48b7f9a6..178de4aca 100644
--- a/libc/include/sys/ioctl.h
+++ b/libc/include/sys/ioctl.h
@@ -26,8 +26,12 @@
  * SUCH DAMAGE.
  */
 
-#ifndef _SYS_IOCTL_H_
-#define _SYS_IOCTL_H_
+#pragma once
+
+/**
+ * @file sys/ioctl.h
+ * @brief The ioctl() function.
+ */
 
 #include <sys/cdefs.h>
 #include <linux/ioctl.h>
@@ -39,5 +43,3 @@
 #include <linux/tty.h>
 
 #include <bits/ioctl.h>
-
-#endif
diff --git a/libc/include/sys/ipc.h b/libc/include/sys/ipc.h
index dee7c8a9a..c81ec1a5a 100644
--- a/libc/include/sys/ipc.h
+++ b/libc/include/sys/ipc.h
@@ -26,8 +26,12 @@
  * SUCH DAMAGE.
  */
 
-#ifndef _SYS_IPC_H
-#define _SYS_IPC_H
+#pragma once
+
+/**
+ * @file sys/ipc.h
+ * @brief System V IPC.
+ */
 
 #include <sys/cdefs.h>
 #include <sys/types.h>
@@ -42,8 +46,12 @@
 
 __BEGIN_DECLS
 
+/**
+ * [ftok(3)](http://man7.org/linux/man-pages/man3/ftok.3.html) converts a path and id to a
+ * System V IPC key.
+ *
+ * Returns a key on success, and returns -1 and sets `errno` on failure.
+ */
 key_t ftok(const char* __path, int __id);
 
 __END_DECLS
-
-#endif
diff --git a/libc/include/sys/klog.h b/libc/include/sys/klog.h
index ed746fcc6..b33d11b13 100644
--- a/libc/include/sys/klog.h
+++ b/libc/include/sys/klog.h
@@ -26,28 +26,46 @@
  * SUCH DAMAGE.
  */
 
-#ifndef _SYS_KLOG_H_
-#define _SYS_KLOG_H_
+#pragma once
+
+/**
+ * @file sys/klog.h
+ * @brief
+ */
 
 #include <sys/cdefs.h>
 
 __BEGIN_DECLS
 
-/* These correspond to the kernel's SYSLOG_ACTION_whatever constants. */
-#define KLOG_CLOSE         0
-#define KLOG_OPEN          1
-#define KLOG_READ          2
-#define KLOG_READ_ALL      3
-#define KLOG_READ_CLEAR    4
-#define KLOG_CLEAR         5
-#define KLOG_CONSOLE_OFF   6
-#define KLOG_CONSOLE_ON    7
+/** Used with klogctl(). */
+#define KLOG_CLOSE 0
+/** Used with klogctl(). */
+#define KLOG_OPEN 1
+/** Used with klogctl(). */
+#define KLOG_READ 2
+/** Used with klogctl(). */
+#define KLOG_READ_ALL 3
+/** Used with klogctl(). */
+#define KLOG_READ_CLEAR 4
+/** Used with klogctl(). */
+#define KLOG_CLEAR 5
+/** Used with klogctl(). */
+#define KLOG_CONSOLE_OFF 6
+/** Used with klogctl(). */
+#define KLOG_CONSOLE_ON 7
+/** Used with klogctl(). */
 #define KLOG_CONSOLE_LEVEL 8
-#define KLOG_SIZE_UNREAD   9
-#define KLOG_SIZE_BUFFER   10
+/** Used with klogctl(). */
+#define KLOG_SIZE_UNREAD 9
+/** Used with klogctl(). */
+#define KLOG_SIZE_BUFFER 10
 
+/**
+ * [klogctl(2)](http://man7.org/linux/man-pages/man2/syslog.2.html) operates on the kernel log.
+ *
+ * This system call is not available to applications.
+ * Use syslog() or `<android/log.h>` instead.
+ */
 int klogctl(int __type, char* __buf, int __buf_size);
 
 __END_DECLS
-
-#endif
diff --git a/libc/include/sys/mount.h b/libc/include/sys/mount.h
index c0c084b40..4db1ac1a6 100644
--- a/libc/include/sys/mount.h
+++ b/libc/include/sys/mount.h
@@ -26,8 +26,12 @@
  * SUCH DAMAGE.
  */
 
-#ifndef _SYS_MOUNT_H
-#define _SYS_MOUNT_H
+#pragma once
+
+/**
+ * @file sys/mount.h
+ * @brief Mounting and unmounting filesystems.
+ */
 
 #include <sys/cdefs.h>
 #include <sys/ioctl.h>
@@ -35,16 +39,38 @@
 
 __BEGIN_DECLS
 
-/* umount2 flags. */
+/** The umount2() flag to force unmounting. */
 #define MNT_FORCE 1
+/** The umount2() flag to lazy unmount. */
 #define MNT_DETACH 2
+/** The umount2() flag to mark a mount point as expired. */
 #define MNT_EXPIRE 4
+
+/** The umount2() flag to not dereference the mount point path if it's a symbolic link. */
 #define UMOUNT_NOFOLLOW 8
 
+/**
+ * [mount(2)](http://man7.org/linux/man-pages/man2/mount.2.html) mounts the filesystem `source` at
+ * the mount point `target`.
+ *
+ * Returns 0 on success, and returns -1 and sets `errno` on failure.
+ */
 int mount(const char* __source, const char* __target, const char* __fs_type, unsigned long __flags, const void* __data);
+
+/**
+ * [umount(2)](http://man7.org/linux/man-pages/man2/umount.2.html) unmounts the filesystem at
+ * the given mount point.
+ *
+ * Returns 0 on success, and returns -1 and sets `errno` on failure.
+ */
 int umount(const char* __target);
+
+/**
+ * [umount2(2)](http://man7.org/linux/man-pages/man2/umount2.2.html) unmounts the filesystem at
+ * the given mount point, according to the supplied flags.
+ *
+ * Returns 0 on success, and returns -1 and sets `errno` on failure.
+ */
 int umount2(const char* __target, int __flags);
 
 __END_DECLS
-
-#endif
diff --git a/libc/include/sys/msg.h b/libc/include/sys/msg.h
index 0273499c7..e19452c4e 100644
--- a/libc/include/sys/msg.h
+++ b/libc/include/sys/msg.h
@@ -26,8 +26,12 @@
  * SUCH DAMAGE.
  */
 
-#ifndef _SYS_MSG_H_
-#define _SYS_MSG_H_
+#pragma once
+
+/**
+ * @file sys/msg.h
+ * @brief System V message queues. Not useful on Android because it's disallowed by SELinux.
+ */
 
 #include <sys/cdefs.h>
 #include <sys/ipc.h>
@@ -41,11 +45,13 @@ __BEGIN_DECLS
 typedef __kernel_ulong_t msgqnum_t;
 typedef __kernel_ulong_t msglen_t;
 
+/** Not useful on Android; disallowed by SELinux. */
 int msgctl(int __msg_id, int __cmd, struct msqid_ds* __buf) __INTRODUCED_IN(26);
+/** Not useful on Android; disallowed by SELinux. */
 int msgget(key_t __key, int __flags) __INTRODUCED_IN(26);
+/** Not useful on Android; disallowed by SELinux. */
 ssize_t msgrcv(int __msg_id, void* __msgbuf_ptr, size_t __size, long __type, int __flags) __INTRODUCED_IN(26);
+/** Not useful on Android; disallowed by SELinux. */
 int msgsnd(int __msg_id, const void* __msgbuf_ptr, size_t __size, int __flags) __INTRODUCED_IN(26);
 
 __END_DECLS
-
-#endif
diff --git a/libc/include/sys/param.h b/libc/include/sys/param.h
index ec50da2b9..4a83e9d74 100644
--- a/libc/include/sys/param.h
+++ b/libc/include/sys/param.h
@@ -26,27 +26,34 @@
  * SUCH DAMAGE.
  */
 
-#ifndef _SYS_PARAM_H_
-#define _SYS_PARAM_H_
+#pragma once
+
+/**
+ * @file sys/param.h
+ * @brief Various macros.
+ */
 
 #include <limits.h>
 #include <linux/param.h>
 #include <sys/cdefs.h>
 
+/** The unit of `st_blocks` in `struct stat`. */
 #define DEV_BSIZE 512
 
+/** A historical name for PATH_MAX. */
 #define MAXPATHLEN  PATH_MAX
+
 #define MAXSYMLINKS 8
 
-/* Macros for counting and rounding. */
 #ifndef howmany
 #define howmany(x, y)   (((x)+((y)-1))/(y))
 #endif
 #define roundup(x, y)   ((((x)+((y)-1))/(y))*(y))
-#define powerof2(x)     ((((x)-1)&(x))==0)
 
-/* Macros for min/max. */
+/** Returns true if the argument is a power of two. */
+#define powerof2(x) ((((x)-1)&(x))==0)
+
+/** Returns the lesser of its two arguments. */
 #define MIN(a,b) (((a)<(b))?(a):(b))
+/** Returns the greater of its two arguments. */
 #define MAX(a,b) (((a)>(b))?(a):(b))
-
-#endif
diff --git a/libc/include/sys/personality.h b/libc/include/sys/personality.h
index 51b5cd791..cea0bf829 100644
--- a/libc/include/sys/personality.h
+++ b/libc/include/sys/personality.h
@@ -26,16 +26,26 @@
  * SUCH DAMAGE.
  */
 
-#ifndef _SYS_PERSONALITY_H_
-#define _SYS_PERSONALITY_H_
+#pragma once
+
+/**
+ * @file sys/personality.h
+ * @brief The personality() function.
+ */
 
 #include <sys/cdefs.h>
 #include <linux/personality.h>
 
 __BEGIN_DECLS
 
+/**
+ * [personality(2)](http://man7.org/linux/man-pages/man2/personality.2.html) sets the calling
+ * process' personality.
+ *
+ * Returns the previous persona on success, and returns -1 and sets `errno` on failure.
+ *
+ * Available since API level 15.
+ */
 int personality(unsigned int __persona) __INTRODUCED_IN(15);
 
 __END_DECLS
-
-#endif
diff --git a/libc/include/sys/quota.h b/libc/include/sys/quota.h
index 157c2d9cb..f8faee765 100644
--- a/libc/include/sys/quota.h
+++ b/libc/include/sys/quota.h
@@ -26,8 +26,12 @@
  * SUCH DAMAGE.
  */
 
-#ifndef _SYS_QUOTA_H_
-#define _SYS_QUOTA_H_
+#pragma once
+
+/**
+ * @file sys/quota.h
+ * @brief The quotactl() function.
+ */
 
 #include <sys/cdefs.h>
 
@@ -40,8 +44,13 @@
 
 __BEGIN_DECLS
 
+/**
+ * [quotactl(2)](http://man7.org/linux/man-pages/man2/quotactl.2.html) manipulates disk quotas.
+ *
+ * Returns 0 on success, and returns -1 and sets `errno` on failure.
+ *
+ * Available since API level 26.
+ */
 int quotactl(int __cmd, const char* __special, int __id, char* __addr) __INTRODUCED_IN(26);
 
 __END_DECLS
-
-#endif
diff --git a/libc/include/sys/random.h b/libc/include/sys/random.h
index 4b849f375..be52bd9ca 100644
--- a/libc/include/sys/random.h
+++ b/libc/include/sys/random.h
@@ -26,8 +26,12 @@
  * SUCH DAMAGE.
  */
 
-#ifndef _SYS_RANDOM_H_
-#define _SYS_RANDOM_H_
+#pragma once
+
+/**
+ * @file sys/random.h
+ * @brief The getentropy() and getrandom() functions.
+ */
 
 #include <sys/cdefs.h>
 #include <sys/types.h>
@@ -36,12 +40,28 @@
 
 __BEGIN_DECLS
 
-/* See also arc4random_buf in <stdlib.h>, which is available in all API levels. */
-
+/**
+ * [getentropy(3)](http://man7.org/linux/man-pages/man3/getentropy.3.html) fills the given buffer
+ * with random bytes.
+ *
+ * Returns 0 on success, and returns -1 and sets `errno` on failure.
+ *
+ * Available since API level 28.
+ *
+ * See also arc4random_buf() which is available in all API levels.
+ */
 int getentropy(void* __buffer, size_t __buffer_size) __wur __INTRODUCED_IN(28);
 
+/**
+ * [getrandom(2)](http://man7.org/linux/man-pages/man2/getrandom.2.html) fills the given buffer
+ * with random bytes.
+ *
+ * Returns the number of bytes copied on success, and returns -1 and sets `errno` on failure.
+ *
+ * Available since API level 28.
+ *
+ * See also arc4random_buf() which is available in all API levels.
+ */
 ssize_t getrandom(void* __buffer, size_t __buffer_size, unsigned int __flags) __wur __INTRODUCED_IN(28);
 
 __END_DECLS
-
-#endif
diff --git a/libc/include/sys/reboot.h b/libc/include/sys/reboot.h
index c0c4860ed..156d94779 100644
--- a/libc/include/sys/reboot.h
+++ b/libc/include/sys/reboot.h
@@ -26,24 +26,35 @@
  * SUCH DAMAGE.
  */
 
-#ifndef _SYS_REBOOT_H_
-#define _SYS_REBOOT_H_
+#pragma once
+
+/**
+ * @file sys/reboot.h
+ * @brief The reboot() function.
+ */
 
 #include <sys/cdefs.h>
 #include <linux/reboot.h>
 
 __BEGIN_DECLS
 
-/* use glibc names as well */
-
-#define RB_AUTOBOOT     LINUX_REBOOT_CMD_RESTART
-#define RB_HALT_SYSTEM  LINUX_REBOOT_CMD_HALT
-#define RB_ENABLE_CAD   LINUX_REBOOT_CMD_CAD_ON
-#define RB_DISABLE_CAD  LINUX_REBOOT_CMD_CAD_OFF
-#define RB_POWER_OFF    LINUX_REBOOT_CMD_POWER_OFF
-
+/** The glibc name for the reboot() flag `LINUX_REBOOT_CMD_RESTART`. */
+#define RB_AUTOBOOT LINUX_REBOOT_CMD_RESTART
+/** The glibc name for the reboot() flag `LINUX_REBOOT_CMD_HALT`. */
+#define RB_HALT_SYSTEM LINUX_REBOOT_CMD_HALT
+/** The glibc name for the reboot() flag `LINUX_REBOOT_CMD_CAD_ON`. */
+#define RB_ENABLE_CAD LINUX_REBOOT_CMD_CAD_ON
+/** The glibc name for the reboot() flag `LINUX_REBOOT_CMD_CAD_OFF`. */
+#define RB_DISABLE_CAD LINUX_REBOOT_CMD_CAD_OFF
+/** The glibc name for the reboot() flag `LINUX_REBOOT_CMD_POWER_OFF`. */
+#define RB_POWER_OFF LINUX_REBOOT_CMD_POWER_OFF
+
+/**
+ * [reboot(2)](http://man7.org/linux/man-pages/man2/reboot.2.html) reboots the device.
+ *
+ * Does not return on successful reboot, returns 0 if CAD was successfully enabled/disabled,
+ * and returns -1 and sets `errno` on failure.
+ */
 int reboot(int __cmd);
 
 __END_DECLS
-
-#endif
diff --git a/libc/include/sys/sendfile.h b/libc/include/sys/sendfile.h
index 97432c04a..60bbde8b8 100644
--- a/libc/include/sys/sendfile.h
+++ b/libc/include/sys/sendfile.h
@@ -26,8 +26,12 @@
  * SUCH DAMAGE.
  */
 
-#ifndef _SYS_SENDFILE_H_
-#define _SYS_SENDFILE_H_
+#pragma once
+
+/**
+ * @file sys/sendfile.h
+ * @brief The sendfile() function.
+ */
 
 #include <sys/cdefs.h>
 #include <sys/types.h>
@@ -38,10 +42,21 @@ __BEGIN_DECLS
 #if defined(__USE_FILE_OFFSET64)
 ssize_t sendfile(int __out_fd, int __in_fd, off_t* __offset, size_t __count) __RENAME(sendfile64) __INTRODUCED_IN(21);
 #else
+/**
+ * [sendfile(2)](http://man7.org/linux/man-pages/man2/sendfile.2.html) copies data directly
+ * between two file descriptors.
+ *
+ * Returns the number of bytes copied on success, and returns -1 and sets `errno` on failure.
+ *
+ * Available since API level 21.
+ */
 ssize_t sendfile(int __out_fd, int __in_fd, off_t* __offset, size_t __count);
 #endif
+
+/**
+ * Like sendfile() but allows using a 64-bit offset
+ * even from a 32-bit process without `__FILE_OFFSET_BITS=64`.
+ */
 ssize_t sendfile64(int __out_fd, int __in_fd, off64_t* __offset, size_t __count) __INTRODUCED_IN(21);
 
 __END_DECLS
-
-#endif
diff --git a/libc/include/sys/shm.h b/libc/include/sys/shm.h
index 4723eba40..a3f84d313 100644
--- a/libc/include/sys/shm.h
+++ b/libc/include/sys/shm.h
@@ -26,8 +26,12 @@
  * SUCH DAMAGE.
  */
 
-#ifndef _SYS_SHM_H_
-#define _SYS_SHM_H_
+#pragma once
+
+/**
+ * @file sys/shm.h
+ * @brief System V shared memory. Not useful on Android because it's disallowed by SELinux.
+ */
 
 #include <sys/cdefs.h>
 #include <sys/ipc.h>
@@ -42,11 +46,13 @@ __BEGIN_DECLS
 
 typedef unsigned long shmatt_t;
 
+/** Not useful on Android; disallowed by SELinux. */
 void* shmat(int __shm_id, const void* __addr, int __flags) __INTRODUCED_IN(26);
+/** Not useful on Android; disallowed by SELinux. */
 int shmctl(int __shm_id, int __cmd, struct shmid_ds* __buf) __INTRODUCED_IN(26);
+/** Not useful on Android; disallowed by SELinux. */
 int shmdt(const void* __addr) __INTRODUCED_IN(26);
+/** Not useful on Android; disallowed by SELinux. */
 int shmget(key_t __key, size_t __size, int __flags) __INTRODUCED_IN(26);
 
 __END_DECLS
-
-#endif
diff --git a/libc/include/sys/signalfd.h b/libc/include/sys/signalfd.h
index 2337cd773..bd911f784 100644
--- a/libc/include/sys/signalfd.h
+++ b/libc/include/sys/signalfd.h
@@ -26,8 +26,12 @@
  * SUCH DAMAGE.
  */
 
-#ifndef _SYS_SIGNALFD_H_
-#define _SYS_SIGNALFD_H_
+#pragma once
+
+/**
+ * @file sys/signalfd.h
+ * @brief File-descriptor based signal interface.
+ */
 
 #include <sys/cdefs.h>
 
@@ -36,9 +40,19 @@
 
 __BEGIN_DECLS
 
+/**
+ * [signalfd(2)](http://man7.org/linux/man-pages/man2/signalfd.2.html) creates/manipulates a
+ * file descriptor for reading signal events.
+ *
+ * Returns the file descriptor on success, and returns -1 and sets `errno` on failure.
+ *
+ * Available since API level 18.
+ */
 int signalfd(int __fd, const sigset_t* __mask, int __flags) __INTRODUCED_IN(18);
+
+/**
+ * Like signalfd() but allows setting a signal mask with RT signals even from a 32-bit process.
+ */
 int signalfd64(int __fd, const sigset64_t* __mask, int __flags) __INTRODUCED_IN(28);
 
 __END_DECLS
-
-#endif
diff --git a/libc/include/sys/swap.h b/libc/include/sys/swap.h
index 8a30ccef5..467b98c2c 100644
--- a/libc/include/sys/swap.h
+++ b/libc/include/sys/swap.h
@@ -26,21 +26,47 @@
  * SUCH DAMAGE.
  */
 
-#ifndef _SYS_SWAP_H_
-#define _SYS_SWAP_H_
+#pragma once
+
+/**
+ * @file sys/swap.h
+ * @brief Swap control.
+ */
 
 #include <sys/cdefs.h>
 
 __BEGIN_DECLS
 
+/** swapon() flag to discard pages. */
 #define SWAP_FLAG_DISCARD 0x10000
+
+/**
+ * swapon() flag to give this swap area a non-default priority.
+ * The priority is also encoded in the flags:
+ * `(priority << SWAP_FLAG_PRIO_SHIFT) & SWAP_FLAG_PRIO_MASK`.
+ */
 #define SWAP_FLAG_PREFER 0x8000
+/** See SWAP_FLAG_PREFER. */
 #define SWAP_FLAG_PRIO_MASK 0x7fff
+/** See SWAP_FLAG_PREFER. */
 #define SWAP_FLAG_PRIO_SHIFT 0
 
+/**
+ * [swapon(2)](http://man7.org/linux/man-pages/man2/swapon.2.html) enables swapping.
+ *
+ * Returns 0 on success, and returns -1 and sets `errno` on failure.
+ *
+ * Available since API level 19.
+ */
 int swapon(const char* __path,  int __flags) __INTRODUCED_IN(19);
+
+/**
+ * [swapoff(2)](http://man7.org/linux/man-pages/man2/swapoff.2.html) disables swapping.
+ *
+ * Returns 0 on success, and returns -1 and sets `errno` on failure.
+ *
+ * Available since API level 19.
+ */
 int swapoff(const char* __path) __INTRODUCED_IN(19);
 
 __END_DECLS
-
-#endif
diff --git a/libc/include/sys/sysinfo.h b/libc/include/sys/sysinfo.h
index 6da02ee4e..4ecf986bc 100644
--- a/libc/include/sys/sysinfo.h
+++ b/libc/include/sys/sysinfo.h
@@ -26,20 +26,63 @@
  * SUCH DAMAGE.
  */
 
-#ifndef _SYS_SYSINFO_H_
-#define _SYS_SYSINFO_H_
+#pragma once
+
+/**
+ * @file sys/sysinfo.h
+ * @brief System information.
+ */
 
 #include <sys/cdefs.h>
 #include <linux/kernel.h>
 
 __BEGIN_DECLS
 
+/**
+ * [sysinfo(2)](http://man7.org/linux/man-pages/man2/sysinfo.2.html) queries system information.
+ *
+ * Returns 0 on success, and returns -1 and sets `errno` on failure.
+ */
 int sysinfo(struct sysinfo* __info);
+
+/**
+ * [get_nprocs_conf(3)](http://man7.org/linux/man-pages/man3/get_nprocs_conf.3.html) returns
+ * the total number of processors in the system.
+ *
+ * Available since API level 23.
+ *
+ * See also sysconf().
+ */
 int get_nprocs_conf(void) __INTRODUCED_IN(23);
+
+/**
+ * [get_nprocs(3)](http://man7.org/linux/man-pages/man3/get_nprocs.3.html) returns
+ * the number of processors in the system that are currently on-line.
+ *
+ * Available since API level 23.
+ *
+ * See also sysconf().
+ */
 int get_nprocs(void) __INTRODUCED_IN(23);
+
+/**
+ * [get_phys_pages(3)](http://man7.org/linux/man-pages/man3/get_phys_pages.3.html) returns
+ * the total number of physical pages in the system.
+ *
+ * Available since API level 23.
+ *
+ * See also sysconf().
+ */
 long get_phys_pages(void) __INTRODUCED_IN(23);
+
+/**
+ * [get_avphys_pages(3)](http://man7.org/linux/man-pages/man3/get_avphys_pages.3.html) returns
+ * the number of physical pages in the system that are currently available.
+ *
+ * Available since API level 23.
+ *
+ * See also sysconf().
+ */
 long get_avphys_pages(void) __INTRODUCED_IN(23);
 
 __END_DECLS
-
-#endif
diff --git a/libc/include/sys/sysmacros.h b/libc/include/sys/sysmacros.h
index 592cc5e0b..64cf28938 100644
--- a/libc/include/sys/sysmacros.h
+++ b/libc/include/sys/sysmacros.h
@@ -26,21 +26,26 @@
  * SUCH DAMAGE.
  */
 
-#ifndef _SYS_SYSMACROS_H_
-#define _SYS_SYSMACROS_H_
+#pragma once
+
+/**
+ * @file sys/sysmacros.h
+ * @brief Major/minor device number macros.
+ */
 
 #include <sys/cdefs.h>
 
+/** Combines `major` and `minor` into a device number. */
 #define makedev(__major, __minor) \
   ( \
     (((__major) & 0xfffff000ULL) << 32) | (((__major) & 0xfffULL) << 8) | \
     (((__minor) & 0xffffff00ULL) << 12) | (((__minor) & 0xffULL)) \
   )
 
+/** Extracts the major part of a device number. */
 #define major(__dev) \
   ((unsigned) ((((unsigned long long) (__dev) >> 32) & 0xfffff000) | (((__dev) >> 8) & 0xfff)))
 
+/** Extracts the minor part of a device number. */
 #define minor(__dev) \
   ((unsigned) ((((__dev) >> 12) & 0xffffff00) | ((__dev) & 0xff)))
-
-#endif /* _SYS_SYSMACROS_H_ */
diff --git a/libc/include/sys/timerfd.h b/libc/include/sys/timerfd.h
index 7bf675ba7..b89941b1e 100644
--- a/libc/include/sys/timerfd.h
+++ b/libc/include/sys/timerfd.h
@@ -26,8 +26,12 @@
  * SUCH DAMAGE.
  */
 
-#ifndef _SYS_TIMERFD_H_
-#define _SYS_TIMERFD_H_
+#pragma once
+
+/**
+ * @file sys/timerfd.h
+ * @brief Timer file descriptors.
+ */
 
 #include <fcntl.h> /* For O_CLOEXEC and O_NONBLOCK. */
 #include <time.h>
@@ -36,16 +40,44 @@
 
 __BEGIN_DECLS
 
-#define TFD_TIMER_ABSTIME (1 << 0)
-#define TFD_TIMER_CANCEL_ON_SET (1 << 1)
-
+/** The timerfd_create() flag for a close-on-exec file descriptor. */
 #define TFD_CLOEXEC O_CLOEXEC
+/** The timerfd_create() flag for a non-blocking file descriptor. */
 #define TFD_NONBLOCK O_NONBLOCK
 
+/**
+ * [timerfd_create(2)](http://man7.org/linux/man-pages/man2/timerfd_create.2.html) creates a
+ * timer file descriptor.
+ *
+ * Returns the new file descriptor on success, and returns -1 and sets `errno` on failure.
+ *
+ * Available since API level 19.
+ */
 int timerfd_create(clockid_t __clock, int __flags) __INTRODUCED_IN(19);
+
+/** The timerfd_settime() flag to use absolute rather than relative times. */
+#define TFD_TIMER_ABSTIME (1 << 0)
+/** The timerfd_settime() flag to cancel an absolute timer if the realtime clock changes. */
+#define TFD_TIMER_CANCEL_ON_SET (1 << 1)
+
+/**
+ * [timerfd_settime(2)](http://man7.org/linux/man-pages/man2/timerfd_settime.2.html) starts or
+ * stops a timer.
+ *
+ * Returns 0 on success, and returns -1 and sets `errno` on failure.
+ *
+ * Available since API level 19.
+ */
 int timerfd_settime(int __fd, int __flags, const struct itimerspec* __new_value, struct itimerspec* __old_value) __INTRODUCED_IN(19);
+
+/**
+ * [timerfd_gettime(2)](http://man7.org/linux/man-pages/man2/timerfd_gettime.2.html) queries the
+ * current timer settings.
+ *
+ * Returns 0 on success, and returns -1 and sets `errno` on failure.
+ *
+ * Available since API level 19.
+ */
 int timerfd_gettime(int __fd, struct itimerspec* __current_value) __INTRODUCED_IN(19);
 
 __END_DECLS
-
-#endif
diff --git a/libc/include/sys/times.h b/libc/include/sys/times.h
index 3c8a4efc1..25d03e388 100644
--- a/libc/include/sys/times.h
+++ b/libc/include/sys/times.h
@@ -26,8 +26,12 @@
  * SUCH DAMAGE.
  */
 
-#ifndef _SYS_TIMES_H_
-#define _SYS_TIMES_H_
+#pragma once
+
+/**
+ * @file sys/times.h
+ * @brief The times() function.
+ */
 
 #include <sys/cdefs.h>
 #include <sys/types.h>
@@ -35,8 +39,13 @@
 
 __BEGIN_DECLS
 
+/**
+ * [times(2)](http://man7.org/linux/man-pages/man2/times.2.html) fills a buffer with the
+ * calling process' CPU usage.
+ *
+ * Returns a (possibly overflowed) absolute time on success,
+ * and returns -1 and sets `errno` on failure.
+ */
 clock_t times(struct tms* __buf);
 
 __END_DECLS
-
-#endif
diff --git a/libc/include/sys/timex.h b/libc/include/sys/timex.h
index 74c86118c..52db5dcfc 100644
--- a/libc/include/sys/timex.h
+++ b/libc/include/sys/timex.h
@@ -26,8 +26,12 @@
  * SUCH DAMAGE.
  */
 
-#ifndef _SYS_TIMEX_H_
-#define _SYS_TIMEX_H_
+#pragma once
+
+/**
+ * @file sys/timex.h
+ * @brief Kernel clock tuning.
+ */
 
 #include <sys/cdefs.h>
 #include <sys/types.h>
@@ -35,9 +39,22 @@
 
 __BEGIN_DECLS
 
+/**
+ * [adjtimex(2)](http://man7.org/linux/man-pages/man2/adjtimex.2.html) adjusts the kernel clock.
+ *
+ * Returns the clock state on success, and returns -1 and sets `errno` on failure.
+ *
+ * Available since API level 24.
+ */
 int adjtimex(struct timex* __buf) __INTRODUCED_IN(24);
+
+/**
+ * clock_adjtime adjusts a specific kernel clock.
+ *
+ * Returns 0 on success, and returns -1 and sets `errno` on failure.
+ *
+ * Available since API level 24.
+ */
 int clock_adjtime(clockid_t __clock, struct timex* __tx) __INTRODUCED_IN(24);
 
 __END_DECLS
-
-#endif
diff --git a/libc/include/sys/un.h b/libc/include/sys/un.h
index 03ef5e423..83c1d1744 100644
--- a/libc/include/sys/un.h
+++ b/libc/include/sys/un.h
@@ -26,8 +26,12 @@
  * SUCH DAMAGE.
  */
 
-#ifndef _SYS_UN_H_
-#define _SYS_UN_H_
+#pragma once
+
+/**
+ * @file sys/un.h
+ * @brief Unix domain sockets.
+ */
 
 #include <bits/sa_family_t.h>
 #include <linux/un.h>
@@ -35,7 +39,6 @@
 
 #if defined(__USE_BSD) || defined(__USE_GNU)
 #include <string.h>
+/** Returns the actual length of the given `sockaddr_un`. */
 #define SUN_LEN(__ptr) (offsetof(struct sockaddr_un, sun_path) + strlen((__ptr)->sun_path))
 #endif
-
-#endif
diff --git a/libc/include/sys/utsname.h b/libc/include/sys/utsname.h
index 2420fb4c9..1fa31871a 100644
--- a/libc/include/sys/utsname.h
+++ b/libc/include/sys/utsname.h
@@ -26,26 +26,42 @@
  * SUCH DAMAGE.
  */
 
-#ifndef _SYS_UTSNAME_H_
-#define _SYS_UTSNAME_H_
+#pragma once
+
+/**
+ * @file sys/utsname.h
+ * @brief The uname() function.
+ */
 
 #include <sys/cdefs.h>
 
 __BEGIN_DECLS
 
+/** The maximum length of any field in `struct utsname`. */
 #define SYS_NMLN 65
 
+/** The information returned by uname(). */
 struct utsname {
+  /** The OS name. "Linux" on Android. */
   char sysname[SYS_NMLN];
+  /** The name on the network. Typically "localhost" on Android. */
   char nodename[SYS_NMLN];
+  /** The OS release. Typically something like "4.4.115-g442ad7fba0d" on Android. */
   char release[SYS_NMLN];
+  /** The OS version. Typically something like "#1 SMP PREEMPT" on Android. */
   char version[SYS_NMLN];
+  /** The hardware architecture. Typically "aarch64" on Android. */
   char machine[SYS_NMLN];
+  /** The domain name set by setdomainname(). Typically "localdomain" on Android. */
   char domainname[SYS_NMLN];
 };
 
+/**
+ * [uname(2)](http://man7.org/linux/man-pages/man2/uname.2.html) returns information
+ * about the kernel.
+ *
+ * Returns 0 on success, and returns -1 and sets `errno` on failure.
+ */
 int uname(struct utsname* __buf);
 
 __END_DECLS
-
-#endif