Basic documentation for android.system.

Also individually @hide the methods we might not want to expose straight
away. These are basically the ones where the mapping to Java types isn't
completely straightforward, usually resulting in a family of similar methods.

Change-Id: I7b3d555c4599dc8c64e23f5c494a358ef68c6777

9 files changed, 510 insertions, 36 deletions

diff --git a/luni/src/main/java/android/system/ErrnoException.java b/luni/src/main/java/android/system/ErrnoException.java
index b434df8..134d6a0 100644
--- a/luni/src/main/java/android/system/ErrnoException.java
+++ b/luni/src/main/java/android/system/ErrnoException.java
@@ -29,13 +29,23 @@ import libcore.io.Libcore;
  */
 public final class ErrnoException extends Exception {
   private final String functionName;
+
+  /**
+   * The errno value, for comparison with the {@code E} constants in {@link OsConstants}.
+   */
   public final int errno;
 
+  /**
+   * Constructs an instance with the given function name and errno value.
+   */
   public ErrnoException(String functionName, int errno) {
     this.functionName = functionName;
     this.errno = errno;
   }
 
+  /**
+   * Constructs an instance with the given function name, errno value, and cause.
+   */
   public ErrnoException(String functionName, int errno, Throwable cause) {
     super(cause);
     this.functionName = functionName;
@@ -56,12 +66,18 @@ public final class ErrnoException extends Exception {
     return functionName + " failed: " + errnoName + " (" + description + ")";
   }
 
+  /**
+   * @hide - internal use only.
+   */
   public IOException rethrowAsIOException() throws IOException {
     IOException newException = new IOException(getMessage());
     newException.initCause(this);
     throw newException;
   }
 
+  /**
+   * @hide - internal use only.
+   */
   public SocketException rethrowAsSocketException() throws SocketException {
     throw new SocketException(getMessage(), this);
   }
diff --git a/luni/src/main/java/android/system/GaiException.java b/luni/src/main/java/android/system/GaiException.java
index 803fc29..dc10566 100644
--- a/luni/src/main/java/android/system/GaiException.java
+++ b/luni/src/main/java/android/system/GaiException.java
@@ -34,11 +34,17 @@ public final class GaiException extends RuntimeException {
    */
   public final int error;
 
+  /**
+   * Constructs an instance with the given function name and error value.
+   */
   public GaiException(String functionName, int error) {
     this.functionName = functionName;
     this.error = error;
   }
 
+  /**
+   * Constructs an instance with the given function name, error value, and cause.
+   */
   public GaiException(String functionName, int error, Throwable cause) {
     super(cause);
     this.functionName = functionName;
@@ -59,12 +65,18 @@ public final class GaiException extends RuntimeException {
     return functionName + " failed: " + gaiName + " (" + description + ")";
   }
 
+  /**
+   * @hide - internal use only.
+   */
   public UnknownHostException rethrowAsUnknownHostException(String detailMessage) throws UnknownHostException {
     UnknownHostException newException = new UnknownHostException(detailMessage);
     newException.initCause(this);
     throw newException;
   }
 
+  /**
+   * @hide - internal use only.
+   */
   public UnknownHostException rethrowAsUnknownHostException() throws UnknownHostException {
     throw rethrowAsUnknownHostException(getMessage());
   }
diff --git a/luni/src/main/java/android/system/Os.java b/luni/src/main/java/android/system/Os.java
index d280ea8..1197c73 100644
--- a/luni/src/main/java/android/system/Os.java
+++ b/luni/src/main/java/android/system/Os.java
@@ -42,122 +42,495 @@ import java.nio.ByteBuffer;
 import libcore.io.Libcore;
 
 /**
+ * Access to low-level system functionality. Most of these are system calls. Most users will want
+ * to use higher-level APIs where available, but this class provides access to the underlying
+ * primitives used to implement the higher-level APIs.
+ *
+ * <p>The corresponding constants can be found in {@link OsConstants}.
+ *
  * @hide
  */
 public final class Os {
   private Os() {}
 
+  /**
+   * See <a href="http://man7.org/linux/man-pages/man2/accept.2.html">accept(2)</a>.
+   */
   public static FileDescriptor accept(FileDescriptor fd, InetSocketAddress peerAddress) throws ErrnoException, SocketException { return Libcore.os.accept(fd, peerAddress); }
+
+  /**
+   * See <a href="http://man7.org/linux/man-pages/man2/access.2.html">access(2)</a>.
+   */
   public static boolean access(String path, int mode) throws ErrnoException { return Libcore.os.access(path, mode); }
+
+  /**
+   * See <a href="http://man7.org/linux/man-pages/man2/bind.2.html">bind(2)</a>.
+   */
   public static void bind(FileDescriptor fd, InetAddress address, int port) throws ErrnoException, SocketException { Libcore.os.bind(fd, address, port); }
+
+  /**
+   * See <a href="http://man7.org/linux/man-pages/man2/chmod.2.html">chmod(2)</a>.
+   */
   public static void chmod(String path, int mode) throws ErrnoException { Libcore.os.chmod(path, mode); }
+
+  /**
+   * See <a href="http://man7.org/linux/man-pages/man2/chown.2.html">chown(2)</a>.
+   */
   public static void chown(String path, int uid, int gid) throws ErrnoException { Libcore.os.chown(path, uid, gid); }
+
+  /**
+   * See <a href="http://man7.org/linux/man-pages/man2/close.2.html">close(2)</a>.
+   */
   public static void close(FileDescriptor fd) throws ErrnoException { Libcore.os.close(fd); }
+
+  /**
+   * See <a href="http://man7.org/linux/man-pages/man2/connect.2.html">connect(2)</a>.
+   */
   public static void connect(FileDescriptor fd, InetAddress address, int port) throws ErrnoException, SocketException { Libcore.os.connect(fd, address, port); }
+
+  /**
+   * See <a href="http://man7.org/linux/man-pages/man2/dup.2.html">dup(2)</a>.
+   */
   public static FileDescriptor dup(FileDescriptor oldFd) throws ErrnoException { return Libcore.os.dup(oldFd); }
+
+  /**
+   * See <a href="http://man7.org/linux/man-pages/man2/dup2.2.html">dup2(2)</a>.
+   */
   public static FileDescriptor dup2(FileDescriptor oldFd, int newFd) throws ErrnoException { return Libcore.os.dup2(oldFd, newFd); }
+
+  /**
+   * See <a href="http://man7.org/linux/man-pages/man3/environ.3.html">environ(3)</a>.
+   */
   public static String[] environ() { return Libcore.os.environ(); }
+
+  /**
+   * See <a href="http://man7.org/linux/man-pages/man2/execv.2.html">execv(2)</a>.
+   */
   public static void execv(String filename, String[] argv) throws ErrnoException { Libcore.os.execv(filename, argv); }
+
+  /**
+   * See <a href="http://man7.org/linux/man-pages/man2/execve.2.html">execve(2)</a>.
+   */
   public static void execve(String filename, String[] argv, String[] envp) throws ErrnoException { Libcore.os.execve(filename, argv, envp); }
+
+  /**
+   * See <a href="http://man7.org/linux/man-pages/man2/fchmod.2.html">fchmod(2)</a>.
+   */
   public static void fchmod(FileDescriptor fd, int mode) throws ErrnoException { Libcore.os.fchmod(fd, mode); }
+
+  /**
+   * See <a href="http://man7.org/linux/man-pages/man2/fchown.2.html">fchown(2)</a>.
+   */
   public static void fchown(FileDescriptor fd, int uid, int gid) throws ErrnoException { Libcore.os.fchown(fd, uid, gid); }
-  public static int fcntlVoid(FileDescriptor fd, int cmd) throws ErrnoException { return Libcore.os.fcntlVoid(fd, cmd); }
-  public static int fcntlLong(FileDescriptor fd, int cmd, long arg) throws ErrnoException { return Libcore.os.fcntlLong(fd, cmd, arg); }
-  public static int fcntlFlock(FileDescriptor fd, int cmd, StructFlock arg) throws ErrnoException { return Libcore.os.fcntlFlock(fd, cmd, arg); }
+
+  /** @hide */ public static int fcntlVoid(FileDescriptor fd, int cmd) throws ErrnoException { return Libcore.os.fcntlVoid(fd, cmd); }
+  /** @hide */ public static int fcntlLong(FileDescriptor fd, int cmd, long arg) throws ErrnoException { return Libcore.os.fcntlLong(fd, cmd, arg); }
+  /** @hide */ public static int fcntlFlock(FileDescriptor fd, int cmd, StructFlock arg) throws ErrnoException { return Libcore.os.fcntlFlock(fd, cmd, arg); }
+
+  /**
+   * See <a href="http://man7.org/linux/man-pages/man2/fdatasync.2.html">fdatasync(2)</a>.
+   */
   public static void fdatasync(FileDescriptor fd) throws ErrnoException { Libcore.os.fdatasync(fd); }
+
+  /**
+   * See <a href="http://man7.org/linux/man-pages/man2/fstat.2.html">fstat(2)</a>.
+   */
   public static StructStat fstat(FileDescriptor fd) throws ErrnoException { return Libcore.os.fstat(fd); }
+
+  /**
+   * See <a href="http://man7.org/linux/man-pages/man2/fstatvfs.2.html">fstatvfs(2)</a>.
+   */
   public static StructStatVfs fstatvfs(FileDescriptor fd) throws ErrnoException { return Libcore.os.fstatvfs(fd); }
+
+  /**
+   * See <a href="http://man7.org/linux/man-pages/man2/fsync.2.html">fsync(2)</a>.
+   */
   public static void fsync(FileDescriptor fd) throws ErrnoException { Libcore.os.fsync(fd); }
+
+  /**
+   * See <a href="http://man7.org/linux/man-pages/man2/ftruncate.2.html">ftruncate(2)</a>.
+   */
   public static void ftruncate(FileDescriptor fd, long length) throws ErrnoException { Libcore.os.ftruncate(fd, length); }
+
+  /**
+   * See <a href="http://man7.org/linux/man-pages/man3/gai_strerror.3.html">gai_strerror(3)</a>.
+   */
   public static String gai_strerror(int error) { return Libcore.os.gai_strerror(error); }
-  public static InetAddress[] getaddrinfo(String node, StructAddrinfo hints) throws GaiException { return Libcore.os.getaddrinfo(node, hints); }
+
+  /** @hide */ public static InetAddress[] getaddrinfo(String node, StructAddrinfo hints) throws GaiException { return Libcore.os.getaddrinfo(node, hints); }
+
+  /**
+   * See <a href="http://man7.org/linux/man-pages/man2/getegid.2.html">getegid(2)</a>.
+   */
   public static int getegid() { return Libcore.os.getegid(); }
+
+  /**
+   * See <a href="http://man7.org/linux/man-pages/man2/geteuid.2.html">geteuid(2)</a>.
+   */
   public static int geteuid() { return Libcore.os.geteuid(); }
+
+  /**
+   * See <a href="http://man7.org/linux/man-pages/man2/getgid.2.html">getgid(2)</a>.
+   */
   public static int getgid() { return Libcore.os.getgid(); }
+
+  /**
+   * See <a href="http://man7.org/linux/man-pages/man3/getenv.3.html">getenv(3)</a>.
+   */
   public static String getenv(String name) { return Libcore.os.getenv(name); }
-  public static String getnameinfo(InetAddress address, int flags) throws GaiException { return Libcore.os.getnameinfo(address, flags); }
+
+  /** @hide */ public static String getnameinfo(InetAddress address, int flags) throws GaiException { return Libcore.os.getnameinfo(address, flags); }
+
+  /**
+   * See <a href="http://man7.org/linux/man-pages/man2/getpeername.2.html">getpeername(2)</a>.
+   */
   public static SocketAddress getpeername(FileDescriptor fd) throws ErrnoException { return Libcore.os.getpeername(fd); }
+
+  /**
+   * See <a href="http://man7.org/linux/man-pages/man2/getpid.2.html">getpid(2)</a>.
+   */
   public static int getpid() { return Libcore.os.getpid(); }
+
+  /**
+   * See <a href="http://man7.org/linux/man-pages/man2/getppid.2.html">getppid(2)</a>.
+   */
   public static int getppid() { return Libcore.os.getppid(); }
-  public static StructPasswd getpwnam(String name) throws ErrnoException { return Libcore.os.getpwnam(name); }
-  public static StructPasswd getpwuid(int uid) throws ErrnoException { return Libcore.os.getpwuid(uid); }
+
+  /** @hide */ public static StructPasswd getpwnam(String name) throws ErrnoException { return Libcore.os.getpwnam(name); }
+
+  /** @hide */ public static StructPasswd getpwuid(int uid) throws ErrnoException { return Libcore.os.getpwuid(uid); }
+
+  /**
+   * See <a href="http://man7.org/linux/man-pages/man2/getsockname.2.html">getsockname(2)</a>.
+   */
   public static SocketAddress getsockname(FileDescriptor fd) throws ErrnoException { return Libcore.os.getsockname(fd); }
-  public static int getsockoptByte(FileDescriptor fd, int level, int option) throws ErrnoException { return Libcore.os.getsockoptByte(fd, level, option); }
-  public static InetAddress getsockoptInAddr(FileDescriptor fd, int level, int option) throws ErrnoException { return Libcore.os.getsockoptInAddr(fd, level, option); }
-  public static int getsockoptInt(FileDescriptor fd, int level, int option) throws ErrnoException { return Libcore.os.getsockoptInt(fd, level, option); }
-  public static StructLinger getsockoptLinger(FileDescriptor fd, int level, int option) throws ErrnoException { return Libcore.os.getsockoptLinger(fd, level, option); }
-  public static StructTimeval getsockoptTimeval(FileDescriptor fd, int level, int option) throws ErrnoException { return Libcore.os.getsockoptTimeval(fd, level, option); }
-  public static StructUcred getsockoptUcred(FileDescriptor fd, int level, int option) throws ErrnoException { return Libcore.os.getsockoptUcred(fd, level, option); }
+
+  /** @hide */ public static int getsockoptByte(FileDescriptor fd, int level, int option) throws ErrnoException { return Libcore.os.getsockoptByte(fd, level, option); }
+  /** @hide */ public static InetAddress getsockoptInAddr(FileDescriptor fd, int level, int option) throws ErrnoException { return Libcore.os.getsockoptInAddr(fd, level, option); }
+  /** @hide */ public static int getsockoptInt(FileDescriptor fd, int level, int option) throws ErrnoException { return Libcore.os.getsockoptInt(fd, level, option); }
+  /** @hide */ public static StructLinger getsockoptLinger(FileDescriptor fd, int level, int option) throws ErrnoException { return Libcore.os.getsockoptLinger(fd, level, option); }
+  /** @hide */ public static StructTimeval getsockoptTimeval(FileDescriptor fd, int level, int option) throws ErrnoException { return Libcore.os.getsockoptTimeval(fd, level, option); }
+  /** @hide */ public static StructUcred getsockoptUcred(FileDescriptor fd, int level, int option) throws ErrnoException { return Libcore.os.getsockoptUcred(fd, level, option); }
+
+  /**
+   * See <a href="http://man7.org/linux/man-pages/man2/gettid.2.html">gettid(2)</a>.
+   */
   public static int gettid() { return Libcore.os.gettid(); }
+
+  /**
+   * See <a href="http://man7.org/linux/man-pages/man2/getuid.2.html">getuid(2)</a>.
+   */
   public static int getuid() { return Libcore.os.getuid(); }
+
+  /**
+   * See <a href="http://man7.org/linux/man-pages/man3/if_indextoname.3.html">if_indextoname(3)</a>.
+   */
   public static String if_indextoname(int index) { return Libcore.os.if_indextoname(index); }
+
+  /**
+   * See <a href="http://man7.org/linux/man-pages/man3/inet_pton.3.html">inet_pton(3)</a>.
+   */
   public static InetAddress inet_pton(int family, String address) { return Libcore.os.inet_pton(family, address); }
-  public static InetAddress ioctlInetAddress(FileDescriptor fd, int cmd, String interfaceName) throws ErrnoException { return Libcore.os.ioctlInetAddress(fd, cmd, interfaceName); }
-  public static int ioctlInt(FileDescriptor fd, int cmd, MutableInt arg) throws ErrnoException { return Libcore.os.ioctlInt(fd, cmd, arg); }
+
+  /** @hide */ public static InetAddress ioctlInetAddress(FileDescriptor fd, int cmd, String interfaceName) throws ErrnoException { return Libcore.os.ioctlInetAddress(fd, cmd, interfaceName); }
+  /** @hide */ public static int ioctlInt(FileDescriptor fd, int cmd, MutableInt arg) throws ErrnoException { return Libcore.os.ioctlInt(fd, cmd, arg); }
+
+  /**
+   * See <a href="http://man7.org/linux/man-pages/man3/isatty.3.html">isatty(3)</a>.
+   */
   public static boolean isatty(FileDescriptor fd) { return Libcore.os.isatty(fd); }
+
+  /**
+   * See <a href="http://man7.org/linux/man-pages/man2/kill.2.html">kill(2)</a>.
+   */
   public static void kill(int pid, int signal) throws ErrnoException { Libcore.os.kill(pid, signal); }
+
+  /**
+   * See <a href="http://man7.org/linux/man-pages/man2/lchown.2.html">lchown(2)</a>.
+   */
   public static void lchown(String path, int uid, int gid) throws ErrnoException { Libcore.os.lchown(path, uid, gid); }
+
+  /**
+   * See <a href="http://man7.org/linux/man-pages/man2/listen.2.html">listen(2)</a>.
+   */
   public static void listen(FileDescriptor fd, int backlog) throws ErrnoException { Libcore.os.listen(fd, backlog); }
+
+  /**
+   * See <a href="http://man7.org/linux/man-pages/man2/lseek.2.html">lseek(2)</a>.
+   */
   public static long lseek(FileDescriptor fd, long offset, int whence) throws ErrnoException { return Libcore.os.lseek(fd, offset, whence); }
+
+  /**
+   * See <a href="http://man7.org/linux/man-pages/man2/lstat.2.html">lstat(2)</a>.
+   */
   public static StructStat lstat(String path) throws ErrnoException { return Libcore.os.lstat(path); }
+
+  /**
+   * See <a href="http://man7.org/linux/man-pages/man2/mincore.2.html">mincore(2)</a>.
+   */
   public static void mincore(long address, long byteCount, byte[] vector) throws ErrnoException { Libcore.os.mincore(address, byteCount, vector); }
+
+  /**
+   * See <a href="http://man7.org/linux/man-pages/man2/mkdir.2.html">mkdir(2)</a>.
+   */
   public static void mkdir(String path, int mode) throws ErrnoException { Libcore.os.mkdir(path, mode); }
+
+  /**
+   * See <a href="http://man7.org/linux/man-pages/man3/mkfifo.3.html">mkfifo(3)</a>.
+   */
   public static void mkfifo(String path, int mode) throws ErrnoException { Libcore.os.mkfifo(path, mode); }
+
+  /**
+   * See <a href="http://man7.org/linux/man-pages/man2/mlock.2.html">mlock(2)</a>.
+   */
   public static void mlock(long address, long byteCount) throws ErrnoException { Libcore.os.mlock(address, byteCount); }
+
+  /**
+   * See <a href="http://man7.org/linux/man-pages/man2/mmap.2.html">mmap(2)</a>.
+   */
   public static long mmap(long address, long byteCount, int prot, int flags, FileDescriptor fd, long offset) throws ErrnoException { return Libcore.os.mmap(address, byteCount, prot, flags, fd, offset); }
+
+  /**
+   * See <a href="http://man7.org/linux/man-pages/man2/msync.2.html">msync(2)</a>.
+   */
   public static void msync(long address, long byteCount, int flags) throws ErrnoException { Libcore.os.msync(address, byteCount, flags); }
+
+  /**
+   * See <a href="http://man7.org/linux/man-pages/man2/munlock.2.html">munlock(2)</a>.
+   */
   public static void munlock(long address, long byteCount) throws ErrnoException { Libcore.os.munlock(address, byteCount); }
+
+  /**
+   * See <a href="http://man7.org/linux/man-pages/man2/munmap.2.html">munmap(2)</a>.
+   */
   public static void munmap(long address, long byteCount) throws ErrnoException { Libcore.os.munmap(address, byteCount); }
+
+  /**
+   * See <a href="http://man7.org/linux/man-pages/man2/open.2.html">open(2)</a>.
+   */
   public static FileDescriptor open(String path, int flags, int mode) throws ErrnoException { return Libcore.os.open(path, flags, mode); }
+
+  /**
+   * See <a href="http://man7.org/linux/man-pages/man2/pipe.2.html">pipe(2)</a>.
+   */
   public static FileDescriptor[] pipe() throws ErrnoException { return Libcore.os.pipe(); }
+
+  /**
+   * See <a href="http://man7.org/linux/man-pages/man2/poll.2.html">poll(2)</a>.
+   */
   public static int poll(StructPollfd[] fds, int timeoutMs) throws ErrnoException { return Libcore.os.poll(fds, timeoutMs); }
+
+  /**
+   * See <a href="http://man7.org/linux/man-pages/man2/posix_fallocate.2.html">posix_fallocate(2)</a>.
+   */
   public static void posix_fallocate(FileDescriptor fd, long offset, long length) throws ErrnoException { Libcore.os.posix_fallocate(fd, offset, length); }
+
+  /**
+   * See <a href="http://man7.org/linux/man-pages/man2/prctl.2.html">prctl(2)</a>.
+   */
   public static int prctl(int option, long arg2, long arg3, long arg4, long arg5) throws ErrnoException { return Libcore.os.prctl(option, arg2, arg3, arg4, arg5); };
+
+  /**
+   * See <a href="http://man7.org/linux/man-pages/man2/pread.2.html">pread(2)</a>.
+   */
   public static int pread(FileDescriptor fd, ByteBuffer buffer, long offset) throws ErrnoException, InterruptedIOException { return Libcore.os.pread(fd, buffer, offset); }
+
+  /**
+   * See <a href="http://man7.org/linux/man-pages/man2/pread.2.html">pread(2)</a>.
+   */
   public static int pread(FileDescriptor fd, byte[] bytes, int byteOffset, int byteCount, long offset) throws ErrnoException, InterruptedIOException { return Libcore.os.pread(fd, bytes, byteOffset, byteCount, offset); }
+
+  /**
+   * See <a href="http://man7.org/linux/man-pages/man2/pwrite.2.html">pwrite(2)</a>.
+   */
   public static int pwrite(FileDescriptor fd, ByteBuffer buffer, long offset) throws ErrnoException, InterruptedIOException { return Libcore.os.pwrite(fd, buffer, offset); }
+
+  /**
+   * See <a href="http://man7.org/linux/man-pages/man2/pwrite.2.html">pwrite(2)</a>.
+   */
   public static int pwrite(FileDescriptor fd, byte[] bytes, int byteOffset, int byteCount, long offset) throws ErrnoException, InterruptedIOException { return Libcore.os.pwrite(fd, bytes, byteOffset, byteCount, offset); }
+
+  /**
+   * See <a href="http://man7.org/linux/man-pages/man2/read.2.html">read(2)</a>.
+   */
   public static int read(FileDescriptor fd, ByteBuffer buffer) throws ErrnoException, InterruptedIOException { return Libcore.os.read(fd, buffer); }
+
+  /**
+   * See <a href="http://man7.org/linux/man-pages/man2/read.2.html">read(2)</a>.
+   */
   public static int read(FileDescriptor fd, byte[] bytes, int byteOffset, int byteCount) throws ErrnoException, InterruptedIOException { return Libcore.os.read(fd, bytes, byteOffset, byteCount); }
+
+  /**
+   * See <a href="http://man7.org/linux/man-pages/man2/readlink.2.html">readlink(2)</a>.
+   */
   public static String readlink(String path) throws ErrnoException { return Libcore.os.readlink(path); }
+
+  /**
+   * See <a href="http://man7.org/linux/man-pages/man2/readv.2.html">readv(2)</a>.
+   */
   public static int readv(FileDescriptor fd, Object[] buffers, int[] offsets, int[] byteCounts) throws ErrnoException, InterruptedIOException { return Libcore.os.readv(fd, buffers, offsets, byteCounts); }
+
+  /**
+   * See <a href="http://man7.org/linux/man-pages/man2/recvfrom.2.html">recvfrom(2)</a>.
+   */
   public static int recvfrom(FileDescriptor fd, ByteBuffer buffer, int flags, InetSocketAddress srcAddress) throws ErrnoException, SocketException { return Libcore.os.recvfrom(fd, buffer, flags, srcAddress); }
+
+  /**
+   * See <a href="http://man7.org/linux/man-pages/man2/recvfrom.2.html">recvfrom(2)</a>.
+   */
   public static int recvfrom(FileDescriptor fd, byte[] bytes, int byteOffset, int byteCount, int flags, InetSocketAddress srcAddress) throws ErrnoException, SocketException { return Libcore.os.recvfrom(fd, bytes, byteOffset, byteCount, flags, srcAddress); }
+
+  /**
+   * See <a href="http://man7.org/linux/man-pages/man3/remove.3.html">remove(3)</a>.
+   */
   public static void remove(String path) throws ErrnoException { Libcore.os.remove(path); }
+
+  /**
+   * See <a href="http://man7.org/linux/man-pages/man2/rename.2.html">rename(2)</a>.
+   */
   public static void rename(String oldPath, String newPath) throws ErrnoException { Libcore.os.rename(oldPath, newPath); }
+
+  /**
+   * See <a href="http://man7.org/linux/man-pages/man2/sendfile.2.html">sendfile(2)</a>.
+   */
   public static long sendfile(FileDescriptor outFd, FileDescriptor inFd, MutableLong inOffset, long byteCount) throws ErrnoException { return Libcore.os.sendfile(outFd, inFd, inOffset, byteCount); }
+
+  /**
+   * See <a href="http://man7.org/linux/man-pages/man2/sendto.2.html">sendto(2)</a>.
+   */
   public static int sendto(FileDescriptor fd, ByteBuffer buffer, int flags, InetAddress inetAddress, int port) throws ErrnoException, SocketException { return Libcore.os.sendto(fd, buffer, flags, inetAddress, port); }
+
+  /**
+   * See <a href="http://man7.org/linux/man-pages/man2/sendto.2.html">sendto(2)</a>.
+   */
   public static int sendto(FileDescriptor fd, byte[] bytes, int byteOffset, int byteCount, int flags, InetAddress inetAddress, int port) throws ErrnoException, SocketException { return Libcore.os.sendto(fd, bytes, byteOffset, byteCount, flags, inetAddress, port); }
+
+  /**
+   * See <a href="http://man7.org/linux/man-pages/man2/setegid.2.html">setegid(2)</a>.
+   */
   public static void setegid(int egid) throws ErrnoException { Libcore.os.setegid(egid); }
+
+  /**
+   * See <a href="http://man7.org/linux/man-pages/man3/setenv.3.html">setenv(3)</a>.
+   */
   public static void setenv(String name, String value, boolean overwrite) throws ErrnoException { Libcore.os.setenv(name, value, overwrite); }
+
+  /**
+   * See <a href="http://man7.org/linux/man-pages/man2/seteuid.2.html">seteuid(2)</a>.
+   */
   public static void seteuid(int euid) throws ErrnoException { Libcore.os.seteuid(euid); }
+
+  /**
+   * See <a href="http://man7.org/linux/man-pages/man2/setgid.2.html">setgid(2)</a>.
+   */
   public static void setgid(int gid) throws ErrnoException { Libcore.os.setgid(gid); }
+
+  /**
+   * See <a href="http://man7.org/linux/man-pages/man2/setsid.2.html">setsid(2)</a>.
+   */
   public static int setsid() throws ErrnoException { return Libcore.os.setsid(); }
-  public static void setsockoptByte(FileDescriptor fd, int level, int option, int value) throws ErrnoException { Libcore.os.setsockoptByte(fd, level, option, value); }
-  public static void setsockoptIfreq(FileDescriptor fd, int level, int option, String value) throws ErrnoException { Libcore.os.setsockoptIfreq(fd, level, option, value); }
-  public static void setsockoptInt(FileDescriptor fd, int level, int option, int value) throws ErrnoException { Libcore.os.setsockoptInt(fd, level, option, value); }
-  public static void setsockoptIpMreqn(FileDescriptor fd, int level, int option, int value) throws ErrnoException { Libcore.os.setsockoptIpMreqn(fd, level, option, value); }
-  public static void setsockoptGroupReq(FileDescriptor fd, int level, int option, StructGroupReq value) throws ErrnoException { Libcore.os.setsockoptGroupReq(fd, level, option, value); }
-  public static void setsockoptGroupSourceReq(FileDescriptor fd, int level, int option, StructGroupSourceReq value) throws ErrnoException { Libcore.os.setsockoptGroupSourceReq(fd, level, option, value); }
-  public static void setsockoptLinger(FileDescriptor fd, int level, int option, StructLinger value) throws ErrnoException { Libcore.os.setsockoptLinger(fd, level, option, value); }
-  public static void setsockoptTimeval(FileDescriptor fd, int level, int option, StructTimeval value) throws ErrnoException { Libcore.os.setsockoptTimeval(fd, level, option, value); }
+
+  /** @hide */ public static void setsockoptByte(FileDescriptor fd, int level, int option, int value) throws ErrnoException { Libcore.os.setsockoptByte(fd, level, option, value); }
+  /** @hide */ public static void setsockoptIfreq(FileDescriptor fd, int level, int option, String value) throws ErrnoException { Libcore.os.setsockoptIfreq(fd, level, option, value); }
+  /** @hide */ public static void setsockoptInt(FileDescriptor fd, int level, int option, int value) throws ErrnoException { Libcore.os.setsockoptInt(fd, level, option, value); }
+  /** @hide */ public static void setsockoptIpMreqn(FileDescriptor fd, int level, int option, int value) throws ErrnoException { Libcore.os.setsockoptIpMreqn(fd, level, option, value); }
+  /** @hide */ public static void setsockoptGroupReq(FileDescriptor fd, int level, int option, StructGroupReq value) throws ErrnoException { Libcore.os.setsockoptGroupReq(fd, level, option, value); }
+  /** @hide */ public static void setsockoptGroupSourceReq(FileDescriptor fd, int level, int option, StructGroupSourceReq value) throws ErrnoException { Libcore.os.setsockoptGroupSourceReq(fd, level, option, value); }
+  /** @hide */ public static void setsockoptLinger(FileDescriptor fd, int level, int option, StructLinger value) throws ErrnoException { Libcore.os.setsockoptLinger(fd, level, option, value); }
+  /** @hide */ public static void setsockoptTimeval(FileDescriptor fd, int level, int option, StructTimeval value) throws ErrnoException { Libcore.os.setsockoptTimeval(fd, level, option, value); }
+
+  /**
+   * See <a href="http://man7.org/linux/man-pages/man2/setuid.2.html">setuid(2)</a>.
+   */
   public static void setuid(int uid) throws ErrnoException { Libcore.os.setuid(uid); }
+
+  /**
+   * See <a href="http://man7.org/linux/man-pages/man2/shutdown.2.html">shutdown(2)</a>.
+   */
   public static void shutdown(FileDescriptor fd, int how) throws ErrnoException { Libcore.os.shutdown(fd, how); }
+
+  /**
+   * See <a href="http://man7.org/linux/man-pages/man2/socket.2.html">socket(2)</a>.
+   */
   public static FileDescriptor socket(int domain, int type, int protocol) throws ErrnoException { return Libcore.os.socket(domain, type, protocol); }
+
+  /**
+   * See <a href="http://man7.org/linux/man-pages/man2/socketpair.2.html">socketpair(2)</a>.
+   */
   public static void socketpair(int domain, int type, int protocol, FileDescriptor fd1, FileDescriptor fd2) throws ErrnoException { Libcore.os.socketpair(domain, type, protocol, fd1, fd2); }
+
+  /**
+   * See <a href="http://man7.org/linux/man-pages/man2/stat.2.html">stat(2)</a>.
+   */
   public static StructStat stat(String path) throws ErrnoException { return Libcore.os.stat(path); }
+
+  /**
+   * See <a href="http://man7.org/linux/man-pages/man2/statvfs.2.html">statvfs(2)</a>.
+   */
   public static StructStatVfs statvfs(String path) throws ErrnoException { return Libcore.os.statvfs(path); }
+
+  /**
+   * See <a href="http://man7.org/linux/man-pages/man3/strerror.3.html">strerror(2)</a>.
+   */
   public static String strerror(int errno) { return Libcore.os.strerror(errno); }
+
+  /**
+   * See <a href="http://man7.org/linux/man-pages/man3/strsignal.3.html">strsignal(3)</a>.
+   */
   public static String strsignal(int signal) { return Libcore.os.strsignal(signal); }
+
+  /**
+   * See <a href="http://man7.org/linux/man-pages/man2/symlink.2.html">symlink(2)</a>.
+   */
   public static void symlink(String oldPath, String newPath) throws ErrnoException { Libcore.os.symlink(oldPath, newPath); }
+
+  /**
+   * See <a href="http://man7.org/linux/man-pages/man3/sysconf.3.html">sysconf(3)</a>.
+   */
   public static long sysconf(int name) { return Libcore.os.sysconf(name); }
+
+  /**
+   * See <a href="http://man7.org/linux/man-pages/man3/tcdrain.3.html">tcdrain(3)</a>.
+   */
   public static void tcdrain(FileDescriptor fd) throws ErrnoException { Libcore.os.tcdrain(fd); }
+
+  /**
+   * See <a href="http://man7.org/linux/man-pages/man3/tcsendbreak.3.html">tcsendbreak(3)</a>.
+   */
   public static void tcsendbreak(FileDescriptor fd, int duration) throws ErrnoException { Libcore.os.tcsendbreak(fd, duration); }
+
+  /**
+   * See <a href="http://man7.org/linux/man-pages/man2/umask.2.html">umask(2)</a>.
+   */
   public static int umask(int mask) { return Libcore.os.umask(mask); }
+
+  /**
+   * See <a href="http://man7.org/linux/man-pages/man2/uname.2.html">uname(2)</a>.
+   */
   public static StructUtsname uname() { return Libcore.os.uname(); }
+
+  /**
+   * See <a href="http://man7.org/linux/man-pages/man3/unsetenv.3.html">unsetenv(3)</a>.
+   */
   public static void unsetenv(String name) throws ErrnoException { Libcore.os.unsetenv(name); }
+
+  /**
+   * See <a href="http://man7.org/linux/man-pages/man2/waitpid.2.html">waitpid(2)</a>.
+   */
   public static int waitpid(int pid, MutableInt status, int options) throws ErrnoException { return Libcore.os.waitpid(pid, status, options); }
+
+  /**
+   * See <a href="http://man7.org/linux/man-pages/man2/write.2.html">write(2)</a>.
+   */
   public static int write(FileDescriptor fd, ByteBuffer buffer) throws ErrnoException, InterruptedIOException { return Libcore.os.write(fd, buffer); }
+
+  /**
+   * See <a href="http://man7.org/linux/man-pages/man2/write.2.html">write(2)</a>.
+   */
   public static int write(FileDescriptor fd, byte[] bytes, int byteOffset, int byteCount) throws ErrnoException, InterruptedIOException { return Libcore.os.write(fd, bytes, byteOffset, byteCount); }
+
+  /**
+   * See <a href="http://man7.org/linux/man-pages/man2/writev.2.html">writev(2)</a>.
+   */
   public static int writev(FileDescriptor fd, Object[] buffers, int[] offsets, int[] byteCounts) throws ErrnoException, InterruptedIOException { return Libcore.os.writev(fd, buffers, offsets, byteCounts); }
 }
diff --git a/luni/src/main/java/android/system/OsConstants.java b/luni/src/main/java/android/system/OsConstants.java
index 3bf70f6..cfed2f6 100644
--- a/luni/src/main/java/android/system/OsConstants.java
+++ b/luni/src/main/java/android/system/OsConstants.java
@@ -17,25 +17,81 @@
 package android.system;
 
 /**
+ * Constants and helper functions for use with {@link Os}.
  * @hide
  */
 public final class OsConstants {
-    private OsConstants() { }
+    private OsConstants() {
+    }
 
+    /**
+     * Tests whether the given mode is a block device.
+     */
     public static boolean S_ISBLK(int mode) { return (mode & S_IFMT) == S_IFBLK; }
+
+    /**
+     * Tests whether the given mode is a character device.
+     */
     public static boolean S_ISCHR(int mode) { return (mode & S_IFMT) == S_IFCHR; }
+
+    /**
+     * Tests whether the given mode is a directory.
+     */
     public static boolean S_ISDIR(int mode) { return (mode & S_IFMT) == S_IFDIR; }
+
+    /**
+     * Tests whether the given mode is a FIFO.
+     */
     public static boolean S_ISFIFO(int mode) { return (mode & S_IFMT) == S_IFIFO; }
+
+    /**
+     * Tests whether the given mode is a regular file.
+     */
     public static boolean S_ISREG(int mode) { return (mode & S_IFMT) == S_IFREG; }
+
+    /**
+     * Tests whether the given mode is a symbolic link.
+     */
     public static boolean S_ISLNK(int mode) { return (mode & S_IFMT) == S_IFLNK; }
+
+    /**
+     * Tests whether the given mode is a socket.
+     */
     public static boolean S_ISSOCK(int mode) { return (mode & S_IFMT) == S_IFSOCK; }
 
+    /**
+     * Extracts the exit status of a child. Only valid if WIFEXITED returns true.
+     */
     public static int WEXITSTATUS(int status) { return (status & 0xff00) >> 8; }
+
+    /**
+     * Tests whether the child dumped core. Only valid if WIFSIGNALED returns true.
+     */
     public static boolean WCOREDUMP(int status) { return (status & 0x80) != 0; }
+
+    /**
+     * Returns the signal that caused the child to exit. Only valid if WIFSIGNALED returns true.
+     */
     public static int WTERMSIG(int status) { return status & 0x7f; }
+
+    /**
+     * Returns the signal that cause the child to stop. Only valid if WIFSTOPPED returns true.
+     */
     public static int WSTOPSIG(int status) { return WEXITSTATUS(status); }
+
+    /**
+     * Tests whether the child exited normally.
+     */
     public static boolean WIFEXITED(int status) { return (WTERMSIG(status) == 0); }
+
+    /**
+     * Tests whether the child was stopped (not terminated) by a signal.
+     */
     public static boolean WIFSTOPPED(int status) { return (WTERMSIG(status) == 0x7f); }
+
+    /**
+     * Tests whether the child was terminated by a signal.
+     */
     public static boolean WIFSIGNALED(int status) { return (WTERMSIG(status + 1) >= 2); }
 
     public static final int AF_INET = placeholder();
@@ -499,6 +555,10 @@ public final class OsConstants {
     public static final int _SC_XOPEN_VERSION = placeholder();
     public static final int _SC_XOPEN_XCU_VERSION = placeholder();
 
+    /**
+     * Returns the string name of a getaddrinfo(3) error value.
+     * For example, "EAI_AGAIN".
+     */
     public static String gaiName(int error) {
         if (error == EAI_AGAIN) {
             return "EAI_AGAIN";
@@ -536,6 +596,10 @@ public final class OsConstants {
         return null;
     }
 
+    /**
+     * Returns the string name of an errno value.
+     * For example, "EACCES". See {@link Os#strerror} for human-readable errno descriptions.
+     */
     public static String errnoName(int errno) {
         if (errno == E2BIG) {
             return "E2BIG";
diff --git a/luni/src/main/java/android/system/StructPasswd.java b/luni/src/main/java/android/system/StructPasswd.java
index 303973e..04a7826 100644
--- a/luni/src/main/java/android/system/StructPasswd.java
+++ b/luni/src/main/java/android/system/StructPasswd.java
@@ -19,9 +19,8 @@ package android.system;
 import libcore.util.Objects;
 
 /**
- * Information returned by getpwnam(3) and getpwuid(3). Corresponds to C's
- * {@code struct passwd} from
- * <a href="http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/pwd.h.html">&lt;pwd.h&gt;</a>
+ * Information returned by {@link Os#getpwnam} and {@link Os#getpwuid}. Corresponds to C's
+ * {@code struct passwd} from {@code &lt;pwd.h&gt;}.
  *
  * @hide
  */
@@ -32,6 +31,9 @@ public final class StructPasswd {
   public final String pw_dir;
   public final String pw_shell;
 
+  /**
+   * Constructs an instance with the given field values.
+   */
   public StructPasswd(String pw_name, int pw_uid, int pw_gid, String pw_dir, String pw_shell) {
     this.pw_name = pw_name;
     this.pw_uid = pw_uid;
diff --git a/luni/src/main/java/android/system/StructPollfd.java b/luni/src/main/java/android/system/StructPollfd.java
index b9526bf..8bdecb2 100644
--- a/luni/src/main/java/android/system/StructPollfd.java
+++ b/luni/src/main/java/android/system/StructPollfd.java
@@ -20,8 +20,8 @@ import java.io.FileDescriptor;
 import libcore.util.Objects;
 
 /**
- * Corresponds to C's {@code struct pollfd} from
- * <a href="http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/poll.h.html">&lt;poll.h&gt;</a>
+ * Used as an in/out parameter to {@link Os#poll}.
+ * Corresponds to C's {@code struct pollfd} from {@code &lt;poll.h&gt;}.
  *
  * @hide
  */
diff --git a/luni/src/main/java/android/system/StructStat.java b/luni/src/main/java/android/system/StructStat.java
index 92e8512..87bd50c 100644
--- a/luni/src/main/java/android/system/StructStat.java
+++ b/luni/src/main/java/android/system/StructStat.java
@@ -19,9 +19,8 @@ package android.system;
 import libcore.util.Objects;
 
 /**
- * File information returned by fstat(2), lstat(2), and stat(2). Corresponds to C's
- * {@code struct stat} from
- * <a href="http://www.opengroup.org/onlinepubs/000095399/basedefs/sys/stat.h.html">&lt;stat.h&gt;</a>
+ * File information returned by {@link Os#fstat}, {@link Os#lstat}, and {@link Os#stat}.
+ * Corresponds to C's {@code struct stat} from {@code &lt;stat.h&gt;}.
  *
  * @hide
  */
@@ -74,6 +73,9 @@ public final class StructStat {
   /** Number of blocks allocated for this object. */
   public final long st_blocks; /*blkcnt_t*/
 
+  /**
+   * Constructs an instance with the given field values.
+   */
   public StructStat(long st_dev, long st_ino, int st_mode, long st_nlink, int st_uid, int st_gid,
                     long st_rdev, long st_size, long st_atime, long st_mtime, long st_ctime,
                     long st_blksize, long st_blocks) {
diff --git a/luni/src/main/java/android/system/StructStatVfs.java b/luni/src/main/java/android/system/StructStatVfs.java
index 1d398af..b0b7802 100644
--- a/luni/src/main/java/android/system/StructStatVfs.java
+++ b/luni/src/main/java/android/system/StructStatVfs.java
@@ -19,7 +19,7 @@ package android.system;
 import libcore.util.Objects;
 
 /**
- * File information returned by fstatvfs(2) and statvfs(2).
+ * File information returned by {@link Os#fstatvfs} and {@link Os#statvfs}.
  *
  * @hide
  */
@@ -57,6 +57,9 @@ public final class StructStatVfs {
   /** Maximum filename length. */
   public final long f_namemax; /*unsigned long*/
 
+  /**
+   * Constructs an instance with the given field values.
+   */
   public StructStatVfs(long f_bsize, long f_frsize, long f_blocks, long f_bfree, long f_bavail,
                 long f_files, long f_ffree, long f_favail,
                 long f_fsid, long f_flag, long f_namemax) {
diff --git a/luni/src/main/java/android/system/StructUtsname.java b/luni/src/main/java/android/system/StructUtsname.java
index 2b7937c..c62dbfa 100644
--- a/luni/src/main/java/android/system/StructUtsname.java
+++ b/luni/src/main/java/android/system/StructUtsname.java
@@ -19,9 +19,8 @@ package android.system;
 import libcore.util.Objects;
 
 /**
- * Information returned by uname(2). Corresponds to C's
- * {@code struct utsname} from
- * <a href="http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/sys_utsname.h.html">&lt;sys/utsname.h&gt;</a>
+ * Information returned by {@link Os#uname}.
+ * Corresponds to C's {@code struct utsname} from {@code &lt;sys/utsname.h&gt;}.
  *
  * @hide
  */
@@ -41,6 +40,9 @@ public final class StructUtsname {
   /** The machine architecture, such as "armv7l" or "x86_64". */
   public final String machine;
 
+  /**
+   * Constructs an instance with the given field values.
+   */
   public StructUtsname(String sysname, String nodename, String release, String version, String machine) {
     this.sysname = sysname;
     this.nodename = nodename;