Change up documentation structure

.gitignore

@@ -4,7 +4,7 @@ dist/
 build/
 aminet/
 Disk.info
-test/
+private-test/
 stuff/
 patches/
 .vamosrc

API.md

@@ -3,7 +3,9 @@
 Most functions will return -2 if the bsdsocket.library is
 not open.
 
-### Setup
+---
+
+## Setup
 
 #### ADDR=Socket Library Open
 
@@ -16,11 +18,15 @@ Try to open bsdsocket.library version 4.
   * If needed, you'll be able to directly access library functions
     using this address.
 
+---
+
 #### Socket Library Close
 
 Close bsdsocket.library. This is safe to call if the library
 is not open
 
+---
+
 #### RESULT=Socket Set Nonblocking(Socket, IsNonblocking BOOL)
 
 Make a socket blocking (False, default), or nonblocking (True).
@@ -29,6 +35,8 @@ Make a socket blocking (False, default), or nonblocking (True).
 
 * Result of IoctlSocket call.
 
+---
+
 #### RESULT=Socket Reuse Addr(Socket)
 
 Make a listening socket reuse the address it's trying to bind to.
@@ -38,9 +46,9 @@ You probably want to call this right before Socket Listen.
 
 * Result of setsockopt call.
 
+---
 
-
+## Connections
-### Connections
 
 #### SOCKET=Socket Create Inet Socket
 
@@ -51,6 +59,8 @@ Create a new Internet socket for reading or writing.
 * Socket number on success
 * -1 on failure
 
+---
+
 #### RESULT=Socket Connect(Socket to IPAddress$, Port)
 
 Attempt to connect to a remote host. Currently doesn't
@@ -65,6 +75,8 @@ support DNS lookups.
     to see if the connection succeeded
 * -11 port out of range
 
+---
+
 #### RESULT=Socket Reuse Addr(Socket)
 
 Set a server socket to reuse an interface and port that had
@@ -77,6 +89,8 @@ setsockopt() for you.
 The result of calling setsockopt() while setting your socket
 to reuse addresses.
 
+---
+
 #### RESULT=Socket Bind(Socket to IPAddress, Port)
 
 Attempt to bind a socket to a network interface. Use
@@ -89,6 +103,8 @@ interfaces.
 * -1 on other error
 * -11 port out of range
 
+---
+
 #### RESULT=Socket Listen(Socket)
 
 Start listening for connections.
@@ -98,6 +114,8 @@ Start listening for connections.
 * 0 on success
 * -1 on failure
 
+---
+
 #### NEW_SOCKET=Socket Accept(Socket)
 
 Get the socket that connected to this one. Wait for a connect
@@ -115,11 +133,13 @@ socket non-blocking and use Fdsets and Select!
 * The remote socket number on success
 * -1 on failure
 
-#### RESULT=Socket Async Wait Reading(Socket, Wait_ms)
+---
+
+#### RESULT=Socket Wait Async Reading(Socket, Wait_ms)
 
 Wait the given number of milliseconds for the nonblocking socket to be ready for reading.
-Use this when you're waiting for a client to connect to you, or if you're waiting for
+Use on a listen socket to await new connections, or on a connected socket to await
-a remote socket to send you data.
+incoming data packets.
 
 ##### Returns
 
@@ -127,7 +147,9 @@ a remote socket to send you data.
 * -1 on error. Use `Socket Errno` for more detail.
 * 1 on success.
 
-#### RESULT=Socket Async Wait Writing(Socket, Wait_ms)
+---
+
+#### RESULT=Socket Wait Async Writing(Socket, Wait_ms)
 
 Wait the given number of milliseconds for the nonblocking socket to be ready for writing.
 Use this when you're connecting to a remote server and want to know if the connection
@@ -143,6 +165,8 @@ has been completed.
     checks will return 1.
 * 1 on success.
 
+---
+
 #### RESULT=Socket Set Timeout(Socket, Wait_ms)
 
 Set a socket to timeout after Wait_ms milliseconds if reading or writing doesn't complete.
@@ -152,7 +176,9 @@ Set a socket to timeout after Wait_ms milliseconds if reading or writing doesn't
 * 0 on success
 * -1 on error
 
-#### RESULT=Socket Close(Socket)
+---
+
+#### RESULT=Socket Close Socket(Socket)
 
 Close a socket.
 
@@ -161,9 +187,9 @@ Close a socket.
 * 0 on success
 * -1 on error
 
+---
 
-
+## Data Transfers
-### Data Transfers
 
 #### SENT=Socket Send$(Socket, String$)
 
@@ -194,6 +220,8 @@ End Proc
 * Number of characters sent
 * -1 on other error
 
+---
+
 #### SENT=Socket Send(Socket, Data Pointer, Length)
 
 Send a block of data to a connected socket.
@@ -203,6 +231,8 @@ Send a block of data to a connected socket.
 * Number of characters sent
 * -1 on other error
 
+---
+
 #### DATA$=Socket Recv$(Socket, MaxLength)
 
 Retrieve at most MaxLength bytes from Socket, and put them into a string.
@@ -212,7 +242,9 @@ If Len(DATA$) < MaxLength, you've read the last bit of data from the socket.
 
 * String of data, which is blank if there is no more data.
 
-### LENGTH=Socket Recv(Socket to Dataptr, MaxLength)
+---
+
+#### LENGTH=Socket Recv(Socket to Dataptr, MaxLength)
 
 Retrieve at most MaxLength bytes from Socket, and put them into the memory
 address at Dataptr.
@@ -222,9 +254,9 @@ address at Dataptr.
 * Count of bytes read
 * -1 on error
 
+---
 
-
+## Informational
-### Informational
 
 #### HOST=Socket Get Host(Socket)
 
@@ -234,6 +266,8 @@ Get the IPv4 (Long) host value the given socket is using.
 
 * Host as a long value
 
+---
+
 #### PORT=Socket Get Port(Socket)
 
 Get the 16-bit port (Word) value the given socket is using.
@@ -242,6 +276,8 @@ Get the 16-bit port (Word) value the given socket is using.
 
 * Port as a word value
 
+---
+
 #### RESULT$=Socket Inet Ntoa$(Host)
 
 Turn a long Host address into a string.
@@ -250,6 +286,8 @@ Turn a long Host address into a string.
 
 * IP address as string
 
+---
+
 #### RESULT=Socket Errno
 
 Get the error from the last command. Note that this is
@@ -260,6 +298,18 @@ not cleared on a successful command!
 Error number from last call. Look in <sys/error.h> for more
 details.
 
+---
+
+#### RESULT=Socket Herrno
+
+Get the error from the last DNS resolver command.
+
+##### Returns
+
+Resolver error number (`h_errno`) from last call.
+
+---
+
 #### RESULT$=Dns Get Address By Name$(Domain Name$)
 
 Look up the first IP address associated with this hostname.
@@ -274,6 +324,8 @@ out. There's no way to set this timeout, or cancel or override it via AMOS.
 
 String with IP address, or blank string on error.
 
+---
+
 #### RESULT=Socket Status(Socket)
 
 Returns basic connection information about a socket.
@@ -297,9 +349,9 @@ Status of socket:
 * 6 = Connecting
 * 7 = Connected
 
+---
 
-
+## Low Level
-### Low Level
 
 #### RESULT=Socket Setsockopt Int(Socket, Option, Value)
 
@@ -311,6 +363,8 @@ Socket Reuse Addr().
 
 * Result of setsockopt call
 
+---
+
 #### RESULT=Socket Getsockopt Int(Socket, Option)
 
 Get a socket option. You probably want SO_ERROR,
@@ -321,6 +375,8 @@ attempt a connection with a non-blocking socket.
 
 * Result of getsockopt call
 
+---
+
 #### ADDR=Socket Fdset Zero(fd_set)
 
 Clear out the specified fd_set.
@@ -330,6 +386,8 @@ Clear out the specified fd_set.
 * Address to that particular fd_set
 * -1 if fd_set out of range. You get 16 of them.
 
+---
+
 #### ADDR=Socket Fdset Set(fd_set, Socket to Value BOOL)
 
 Set or clear a socket bit in an fd_set.
@@ -339,6 +397,8 @@ Set or clear a socket bit in an fd_set.
 * Address to that particular fd_set
 * -1 if fd_set is out of range or socket is out of range.
 
+---
+
 #### RESULT=Socket Fdset Is Set(fd_set, Socket)
 
 See if the particular socket remained after a Socket Select call.
@@ -347,6 +407,8 @@ See if the particular socket remained after a Socket Select call.
 
 * True or False if the socket is set or not
 
+---
+
 #### RESULT=Socket Select(Max Socket, Read fd_set, Write fd_set, Error fd_set, TimeoutMS)
 
 Wait for the specified number of milliseconds. If any of the sockets