Fixes for the docs

Fix some typos, shorten lines, document SOCK_ERROR_EINPROGRESS

plugins/include/sockets.inc

@@ -21,45 +21,71 @@
 	#pragma loadlib sockets
 #endif
 
-// Socket flags
+/*
-#define SOCK_NON_BLOCKING (1 << 0)    // Set the socket a nonblocking
+ * Socket connection type (TCP/UDP)
-#define SOCK_LIBC_ERRORS  (1 << 1)    // Enable libc error reporting
+ */
-
-// Error reporting
-#define SOCK_ERROR_OK               0 // No error
-#define SOCK_ERROR_CREATE_SOCKET    1 // Couldn't create a socket
-#define SOCK_ERROR_SERVER_UNKNOWN   2 // Server unknown
-#define SOCK_ERROR_WHILE_CONNECTING 3 // Error while connecting
-
-// Nonblocking sockets error handler
-stock SOCK_ERROR_EINPROGRESS(error) return (error == 0 || error == 10035 || error == 10036 || error == 115)
-
-// Socket connection type (TCP/UDP)
 #define SOCKET_TCP 1
 #define SOCKET_UDP 2
 
+/**
+ * Socket flags
+ */
+#define SOCK_NON_BLOCKING (1 << 0)    /* Set the socket a nonblocking */
+#define SOCK_LIBC_ERRORS  (1 << 1)    /* Enable libc error reporting */
+
+/*
+ * Error reporting
+ */
+#define SOCK_ERROR_OK               0 /* No error */
+#define SOCK_ERROR_CREATE_SOCKET    1 /* Couldn't create a socket */
+#define SOCK_ERROR_SERVER_UNKNOWN   2 /* Server unknown */
+#define SOCK_ERROR_WHILE_CONNECTING 3 /* Error while connecting */
+
+/*
+ * Nonblocking sockets error handler
+ *
+ * @param error    Error code returned by socket_open()
+ *
+ * @note           A newly created nonblocking socket may be still finishing his connection when
+ *                 socket_open() returns the socket descriptor. This stock should be used to
+ *                 check if socket_open() succeded on creating a new socket, and socket_is_writable()
+ *                 should be used later on the socket descriptor when data is about to be sent to check if 
+ *                 the connection ended up being established.
+ *                 
+ *                 
+ * @return         true if the socket is succesfully created and connected or currently connecting
+ *                 false if the socket failed to be created
+ */
+stock bool:SOCK_ERROR_EINPROGRESS(error) return (error == 0 || error == 10035 || error == 10036 || error == 115)
+
 /**
  * Connects to the given node and service via TCP/UDP.
  *
- * @note There's 2 types of error reporting on this function that you can use, for backwards compatibility reasons libc errors are disabled by default
+ * @note There's 2 types of error reporting on this function that you can use.
- * @note Old, default error codes:
+ * @note Default error codes:
  *       0 - No error
  *       1 - Error while creating socket
  *       2 - Couldn't resolve hostname
  *       3 - Couldn't connect
- * @note New, libc error codes:
+ * @note New, more expressive libc error codes:
  *       https://www.gnu.org/software/libc/manual/html_node/Error-Codes.html
  *       https://github.com/torvalds/linux/blob/master/include/uapi/asm-generic/errno.h
  *       https://msdn.microsoft.com/en-us/library/ms740668.aspx
  *
  * @note The currently available bit flags are:
- *       - SOCK_NON_BLOCKING : if set, the socket would be on nonblocking mode
+ *       - SOCK_NON_BLOCKING : if set, the socket will be on nonblocking mode
- *       - SOCK_LIBC_ERRORS : if set, the new libc errors will be seen on _error instead of the old, made up ones
+ *       - SOCK_LIBC_ERRORS : if set, the new libc errors will be seen on _error
- * @note If no flags are set, the behaviour of the function will not be modified (default blocking mode and error reporting).
- * @note Multiple flags may be set at the same time using the | operator. For example, SOCK_NON_BLOCKING|SOCK_LIBC_ERRORS will create a nonblocking socket with libc error codes.
  *
- * @note If you're creating a new nonblocking socket, _hostname should be numeric to avoid calling the name resolution server and potentially blocking the call
+ * @note If no flags are set, the behaviour of the function will not be modified.
- * @note If the socket is a nonblocking one, the returned socket descriptor may be still connecting and further checks should be done with socket_is_writable() before trying to send data
+ *
+ * @note Multiple flags may be set at the same time using the | operator. 
+ *       For example, SOCK_NON_BLOCKING|SOCK_LIBC_ERRORS will create a nonblocking socket with libc error codes.
+ *
+ * @note If you're creating a new nonblocking socket, _hostname should be numeric to avoid calling the 
+ *       name resolution server and potentially blocking the call
+ *
+ * @note If the socket is a nonblocking one, the returned socket descriptor may be still connecting and 
+ *       further checks should be done with socket_is_writable() before trying to send data
  *
  * @param _hostname    Node to connect to
  * @param _port        Service to connect to
@@ -85,13 +111,13 @@ native socket_close(_socket);
 /**
  * Receives data.
  *
- * @note The ammount of bytes than you end up receiving can be less than the one you expected
+ * @note The amount of bytes than you end up receiving can be less than the one you expected
  *
  * @param _socket    Socket descriptor
  * @param _data      Array to save the data
  * @param _length    Length of the array
  *
- * @return           Ammount of bytes received
+ * @return           Amount of bytes received
  *                   0 if the peer closed the connection
  *                   -1 on failure
  */
@@ -100,13 +126,14 @@ native socket_recv(_socket, _data[], _length);
 /**
  * Sends data.
  *
- * @note The ammount of bytes than you end up sending can be less than expected, you're responsible of sending the rest later
+ * @note The amount of bytes that end up being sent may be lower than the total length of the array,
+ *       check the return value and send the rest if needed
  *
  * @param _socket    Socket descriptor
  * @param _data      Array with the data to send
  * @param _length    Length of the array
  *
- * @return           Ammount of bytes sent
+ * @return           Amount of bytes sent
  *                   -1 on failure
  */
 native socket_send(_socket, const _data[], _length);
@@ -114,41 +141,36 @@ native socket_send(_socket, const _data[], _length);
 /**
  * Sends data that can contain null bytes.
  *
- * @note The ammount of bytes than you end up sending can be less than expected, you're responsible of sending the rest later
+ * @note The amount of bytes that end up being sent may be lower than the total length of the array,
+ *       check the return value and send the rest if needed
  *
  * @param _socket    Socket descriptor
  * @param _data      Array with the data to send
  * @param _length    Length of the array
  *
- * @return           Ammount of bytes sent
+ * @return           Amount of bytes sent
  *                   -1 on failure
  */
 native socket_send2(_socket, const _data[], _length);
 
 /**
- * Check if a socket is marked as readable.
+ * Backwards compatible function
  *
- * @note You can use this function to make sure there's something on the socket and avoiding a blocking call
+ * @deprecated Renamed to socket_is_readable
- * @note Set _timeout to 0 avoid blocking the call
- * @note A socket will become readable if there's any data or an EOF
- *
- * @param _socket    Socket descriptor
- * @param _timeout   Ammount of time to block the call waiting for the socket to be marked as readable or for the timeout to expire, in µSeconds (1 sec = 1000000 µsec)
- *
- * @return           1 if the socket is marked as readable
- *                   -1 otherwise
  */
+#pragma deprecated Use socket_is_readable() instead
 native socket_change(_socket, _timeout = 100000);
 
 /**
- * Check if a socket is marked as readable.
+ * Checks if a socket is marked as readable.
  *
  * @note You can use this function to make sure there's something on the socket and avoiding a blocking call
  * @note Set _timeout to 0 avoid blocking the call
  * @note A socket will become readable if there's any data or an EOF
  *
  * @param _socket    Socket descriptor
- * @param _timeout   Ammount of time to block the call waiting for the socket to be marked as readable or for the timeout to expire, in µSeconds (1 sec = 1000000 µsec)
+ * @param _timeout   Amount of time to block the call waiting for the socket to be marked as readable or
+ *                   for the timeout to expire, in µSeconds (1 sec = 1000000 µsec)
  *
  * @return           1 if the socket is marked as readable
  *                   -1 otherwise
@@ -156,14 +178,15 @@ native socket_change(_socket, _timeout = 100000);
 native socket_is_readable(_socket, _timeout = 100000);
 
 /**
- * Check if a socket is marked as writable.
+ * Checks if a socket is marked as writable.
  *
  * @note Use this function to check if a nonblocking socket is ready to be used
  * @note Set _timeout to 0 avoid blocking the call
  * @note An UDP socket is always writable
  *
  * @param _socket    Socket descriptor
- * @param _timeout   Ammount of time to block the call waiting for the socket to be marked as writable or for the timeout to expire, in µSeconds (1 sec = 1000000 µsec)
+ * @param _timeout   Amount of time to block the call waiting for the socket to be marked as writable or
+ *                   for the timeout to expire, in µSeconds (1 sec = 1000000 µsec)
  *
  * @return           1 if the socket is marked as writable
  *                   -1 otherwise