Start documenting libc.
Bug: N/A
Test: N/A
Change-Id: I17345cb72a5ffc3af1688cf5874589cfb1e1fea0
diff --git a/libc/include/poll.h b/libc/include/poll.h
index 6a8f757..13b7385 100644
--- a/libc/include/poll.h
+++ b/libc/include/poll.h
@@ -26,8 +26,12 @@
* SUCH DAMAGE.
*/
-#ifndef _POLL_H_
-#define _POLL_H_
+#pragma once
+
+/**
+ * @file poll.h
+ * @brief Wait for events on a set of file descriptors.
+ */
#include <sys/cdefs.h>
#include <linux/poll.h>
@@ -36,16 +40,38 @@
__BEGIN_DECLS
+/** The type of a file descriptor count, used by poll() and ppoll(). */
typedef unsigned int nfds_t;
-int poll(struct pollfd* __fds, nfds_t __count, int __timeout_ms);
-int ppoll(struct pollfd* __fds, nfds_t __count, const struct timespec* __timeout, const sigset_t* __mask) __INTRODUCED_IN(21);
-int ppoll64(struct pollfd* __fds, nfds_t __count, const struct timespec* __timeout, const sigset64_t* __mask) __INTRODUCED_IN(28);
+/**
+ * [poll(3)](http://man7.org/linux/man-pages/man3/poll.3.html) waits on a set of file descriptors.
+ *
+ * Returns the number of ready file descriptors on success, 0 for timeout,
+ * and returns -1 and sets `errno` on failure.
+ */
+int poll(struct pollfd* _Nonnull __fds, nfds_t __count, int __timeout_ms);
+
+/**
+ * [ppoll(3)](http://man7.org/linux/man-pages/man3/ppoll.3.html) waits on a set of file descriptors
+ * or a signal. Set `__timeout` to null for no timeout. Set `__mask` to null to not set the signal
+ * mask.
+ *
+ * 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 ppoll(struct pollfd* _Nonnull __fds, nfds_t __count, const struct timespec* _Nullable __timeout, const sigset_t* _Nullable __mask) __INTRODUCED_IN(21);
+
+/**
+ * Like ppoll() but allows setting a signal mask with RT signals even from a 32-bit process.
+ */
+int ppoll64(struct pollfd* _Nonnull __fds, nfds_t __count, const struct timespec* _Nullable __timeout, const sigset64_t* _Nullable __mask) __INTRODUCED_IN(28);
#if defined(__BIONIC_INCLUDE_FORTIFY_HEADERS)
+#define _POLL_H_
#include <bits/fortify/poll.h>
+#undef _POLL_H_
#endif
__END_DECLS
-
-#endif