Merge pull request #713 from luvit/docs

Clean up and expand docs for constants/options

Author: SinisterRectus

docs.md

@@ -82,6 +82,7 @@ within the context of luv's Lua API. Low-level implementation details and
 unexposed C functions and types are not documented here except for when they
 are relevant to behavior seen in the Lua module.
 
+- [Constants][]
 - [Error handling][]
 - [Version checking][]
 - [`uv_loop_t`][] — Event loop
@@ -109,14 +110,109 @@ are relevant to behavior seen in the Lua module.
 - [Miscellaneous utilities][]
 - [Metrics operations][]
 
+## Constants
+
+[constants]: #constants
+
+As a Lua library, luv supports and encourages the use of lowercase strings to
+represent options. For example:
+```lua
+-- signal start with string input
+uv.signal_start("sigterm", function(signame)
+  print(signame) -- string output: "sigterm"
+end)
+```
+
+However, luv also superficially exposes libuv constants in a Lua table at
+`uv.constants` where its keys are uppercase constant names and their associated
+values are integers defined internally by libuv. The values from this table may
+be supported as function arguments, but their use may not change the output
+type. For example:
+
+```lua
+-- signal start with integer input
+uv.signal_start(uv.constants.SIGTERM, function(signame)
+  print(signame) -- string output: "sigterm"
+end)
+```
+
+The uppercase constants defined in `uv.constants` that have associated
+lowercase option strings are listed below.
+
+### Address Families
+
+- `AF_UNIX`: "unix"
+- `AF_INET`: "inet"
+- `AF_INET6`: "inet6"
+- `AF_IPX`: "ipx"
+- `AF_NETLINK`: "netlink"
+- `AF_X25`: "x25"
+- `AF_AX25`: "as25"
+- `AF_ATMPVC`: "atmpvc"
+- `AF_APPLETALK`: "appletalk"
+- `AF_PACKET`: "packet"
+
+### Signals
+
+- `SIGHUP`: "sighup"
+- `SIGINT`: "sigint"
+- `SIGQUIT`: "sigquit"
+- `SIGILL`: "sigill"
+- `SIGTRAP`: "sigtrap"
+- `SIGABRT`: "sigabrt"
+- `SIGIOT`: "sigiot"
+- `SIGBUS`: "sigbus"
+- `SIGFPE`: "sigfpe"
+- `SIGKILL`: "sigkill"
+- `SIGUSR1`: "sigusr1"
+- `SIGSEGV`: "sigsegv"
+- `SIGUSR2`: "sigusr2"
+- `SIGPIPE`: "sigpipe"
+- `SIGALRM`: "sigalrm"
+- `SIGTERM`: "sigterm"
+- `SIGCHLD`: "sigchld"
+- `SIGSTKFLT`: "sigstkflt"
+- `SIGCONT`: "sigcont"
+- `SIGSTOP`: "sigstop"
+- `SIGTSTP`: "sigtstp"
+- `SIGBREAK`: "sigbreak"
+- `SIGTTIN`: "sigttin"
+- `SIGTTOU`: "sigttou"
+- `SIGURG`: "sigurg"
+- `SIGXCPU`: "sigxcpu"
+- `SIGXFSZ`: "sigxfsz"
+- `SIGVTALRM`: "sigvtalrm"
+- `SIGPROF`: "sigprof"
+- `SIGWINCH`: "sigwinch"
+- `SIGIO`: "sigio"
+- `SIGPOLL`: "sigpoll"
+- `SIGLOST`: "siglost"
+- `SIGPWR`: "sigpwr"
+- `SIGSYS`: "sigsys"
+
+### Socket Types
+
+- `SOCK_STREAM`: "stream"
+- `SOCK_DGRAM`: "dgram"
+- `SOCK_SEQPACKET`: "seqpacket"
+- `SOCK_RAW`: "raw"
+- `SOCK_RDM`: "rdm"
+
+### TTY Modes
+
+- `TTY_MODE_NORMAL`: "normal"
+- `TTY_MODE_RAW`: "raw"
+- `TTY_MODE_IO`: "io"
+
 ## Error Handling
 
 [Error handling]: #error-handling
 
-In libuv, errors are negative numbered constants; however, while those errors are exposed through `uv.errno`,
-the functions used to handle them are not exposed to luv users. Instead, if an
-internal error is encountered, the luv function will return to the caller an
-assertable `nil, err, name` tuple.
+In libuv, errors are represented by negative numbered constants. While these
+constants are made available in the `uv.errno` table, they are not returned by
+luv funtions and the libuv functions used to handle them are not exposed.
+Instead, if an internal error is encountered, the failing luv function will
+return to the caller an assertable `nil, err, name` tuple:
 
 - `nil` idiomatically indicates failure
 - `err` is a string with the format `{name}: {message}`
@@ -130,10 +226,8 @@ When a function is called successfully, it will return either a value that is
 relevant to the operation of the function, or the integer `0` to indicate
 success, or sometimes nothing at all. These cases are documented below.
 
-### `uv.errno`
-
-A table value which exposes error constants as a map, where the key is the error name (without the `UV_` prefix) and its value is a negative number.
-See Libuv's [Error constants](https://docs.libuv.org/en/v1.x/errors.html#error-constants) page for further details.
+Below is a list of known error names and error strings. See libuv's
+[error constants][] page for an original source.
 
 - `E2BIG`: argument list too long.
 - `EACCES`: permission denied.
@@ -1094,8 +1188,8 @@ Reception of some signals is emulated on Windows:
 -- Create a new signal handler
 local signal = uv.new_signal()
 -- Define a handler function
-uv.signal_start(signal, "sigint", function(signal)
-  print("got " .. signal .. ", shutting down")
+uv.signal_start(signal, "sigint", function(signame)
+  print("got " .. signame .. ", shutting down")
   os.exit(1)
 end)
 ```
@@ -1107,32 +1201,36 @@ it.
 
 **Returns:** `uv_signal_t userdata` or `fail`
 
-### `uv.signal_start(signal, signum, callback)`
+### `uv.signal_start(signal, signame, callback)`
 
-> method form `signal:start(signum, callback)`
+> method form `signal:start(signame, callback)`
 
 **Parameters:**
 - `signal`: `uv_signal_t userdata`
-- `signum`: `integer` or `string`
+- `signame`: `string` or `integer`
 - `callback`: `callable`
-  - `signum`: `string`
+  - `signame`: `string`
 
 Start the handle with the given callback, watching for the given signal.
 
+See [Constants][] for supported `signame` input and output values.
+
 **Returns:** `0` or `fail`
 
-### `uv.signal_start_oneshot(signal, signum, callback)`
+### `uv.signal_start_oneshot(signal, signame, callback)`
 
-> method form `signal:start_oneshot(signum, callback)`
+> method form `signal:start_oneshot(signame, callback)`
 
 **Parameters:**
 - `signal`: `uv_signal_t userdata`
-- `signum`: `integer` or `string`
+- `signame`: `string` or `integer`
 - `callback`: `callable`
-  - `signum`: `string`
+  - `signame`: `string`
 
 Same functionality as `uv.signal_start()` but the signal handler is reset the moment the signal is received.
 
+See [Constants][] for supported `signame` input and output values.
+
 **Returns:** `0` or `fail`
 
 ### `uv.signal_stop(signal)`
@@ -1274,28 +1372,32 @@ When the child process exits, `on_exit` is called with an exit code and signal.
 
 **Returns:** `uv_process_t userdata`, `integer`
 
-### `uv.process_kill(process, signum)`
+### `uv.process_kill(process, signame)`
 
-> method form `process:kill(signum)`
+> method form `process:kill(signame)`
 
 **Parameters:**
 - `process`: `uv_process_t userdata`
-- `signum`: `integer` or `string` or `nil` (default: `sigterm`)
+- `signame`: `string` or `integer` or `nil` (default: `sigterm`)
 
 Sends the specified signal to the given process handle. Check the documentation
 on `uv_signal_t` for signal support, specially on Windows.
 
+See [Constants][] for supported `signame` input values.
+
 **Returns:** `0` or `fail`
 
-### `uv.kill(pid, signum)`
+### `uv.kill(pid, signame)`
 
 **Parameters:**
 - `pid`: `integer`
-- `signum`: `integer` or `string` or `nil` (default: `sigterm`)
+- `signame`: `string` or `integer` or `nil` (default: `sigterm`)
 
 Sends the specified signal to the given PID. Check the documentation on
 `uv_signal_t` for signal support, specially on Windows.
 
+See [Constants][] for supported `signame` input values.
+
 **Returns:** `0` or `fail`
 
 ### `uv.process_get_pid(process)`
@@ -1549,11 +1651,12 @@ TCP handles are used to represent both TCP streams and servers.
 ### `uv.new_tcp([flags])`
 
 **Parameters:**
-- `flags`: `string` or `nil`
+- `flags`: `string` or `integer` or `nil`
 
 Creates and initializes a new `uv_tcp_t`. Returns the Lua userdata wrapping it.
-Flags may be a family string: `"unix"`, `"inet"`, `"inet6"`, `"ipx"`,
-`"netlink"`, `"x25"`, `"ax25"`, `"atmpvc"`, `"appletalk"`, or `"packet"`.
+
+If set, `flags` must be a valid address family. See [Constants][] for supported
+address family input values.
 
 **Returns:** `uv_tcp_t userdata` or `fail`
 
@@ -1649,6 +1752,8 @@ later using `uv.tcp_getsockname()`.
 
 Get the address of the peer connected to the handle.
 
+See [Constants][] for supported address `family` output values.
+
 **Returns:** `table` or `fail`
 - `ip` : `string`
 - `family` : `string`
@@ -1663,6 +1768,8 @@ Get the address of the peer connected to the handle.
 
 Get the current address to which the handle is bound.
 
+See [Constants][] for supported address `family` output values.
+
 **Returns:** `table` or `fail`
 - `ip` : `string`
 - `family` : `string`
@@ -1723,8 +1830,7 @@ and `uv.tcp_close_reset()` calls is not allowed.
 
 Create a pair of connected sockets with the specified properties. The resulting handles can be passed to `uv.tcp_open`, used with `uv.spawn`, or for any other purpose.
 
-When specified as a string, `socktype` must be one of `"stream"`, `"dgram"`, `"raw"`,
-`"rdm"`, or `"seqpacket"`.
+See [Constants][] for supported `socktype` input values.
 
 When `protocol` is set to 0 or nil, it will be automatically chosen based on the socket's domain and type. When `protocol` is specified as a string, it will be looked up using the `getprotobyname(3)` function (examples: `"ip"`, `"icmp"`, `"tcp"`, `"udp"`, etc).
 
@@ -2059,16 +2165,11 @@ This function is not thread safe on systems that don’t support ioctl TIOCGPTN
 
 **Parameters:**
 - `tty`: `uv_tty_t userdata`
-- `mode`: `integer`
+- `mode`: `string` or `integer`
 
 Set the TTY using the specified terminal mode.
 
-Parameter `mode` is a C enum with the following values:
-
-  - 0 - UV_TTY_MODE_NORMAL: Initial/normal terminal mode
-  - 1 - UV_TTY_MODE_RAW: Raw input mode (On Windows, ENABLE_WINDOW_INPUT is
-  also enabled)
-  - 2 - UV_TTY_MODE_IO: Binary-safe I/O mode for IPC (Unix-only)
+See [Constants][] for supported TTY mode input values.
 
 **Returns:** `0` or `fail`
 
@@ -2135,9 +2236,7 @@ UDP handles encapsulate UDP communication for both clients and servers.
 Creates and initializes a new `uv_udp_t`. Returns the Lua userdata wrapping
 it. The actual socket is created lazily.
 
-When specified, `family` must be one of `"unix"`, `"inet"`, `"inet6"`,
-`"ipx"`, `"netlink"`, `"x25"`, `"ax25"`, `"atmpvc"`, `"appletalk"`, or
-`"packet"`.
+See [Constants][] for supported address `family` input values.
 
 When specified, `mmsgs` determines the number of messages able to be received
 at one time via `recvmmsg(2)` (the allocated buffer will be sized to be able
@@ -2386,6 +2485,8 @@ Prepare for receiving data. If the socket has not previously been bound with
 `uv.udp_bind()` it is bound to `0.0.0.0` (the "all interfaces" IPv4 address)
 and a random port number.
 
+See [Constants][] for supported address `family` output values.
+
 **Returns:** `0` or `fail`
 
 ### `uv.udp_recv_stop(udp)`
@@ -3270,12 +3371,14 @@ called in the main loop thread.
 Equivalent to `getaddrinfo(3)`. Either `node` or `service` may be `nil` but not
 both.
 
-Valid hint strings for the keys that take a string:
-- `family`: `"unix"`, `"inet"`, `"inet6"`, `"ipx"`,
-`"netlink"`, `"x25"`, `"ax25"`, `"atmpvc"`, `"appletalk"`, or `"packet"`
-- `socktype`: `"stream"`, `"dgram"`, `"raw"`,
-`"rdm"`, or `"seqpacket"`
-- `protocol`: will be looked up using the `getprotobyname(3)` function (examples: `"ip"`, `"icmp"`, `"tcp"`, `"udp"`, etc)
+See [Constants][] for supported address `family` input and output values.
+
+See [Constants][] for supported `socktype` input and output values.
+
+When `protocol` is set to 0 or nil, it will be automatically chosen based on the
+socket's domain and type. When `protocol` is specified as a string, it will be
+looked up using the `getprotobyname(3)` function. Examples: `"ip"`, `"icmp"`,
+`"tcp"`, `"udp"`, etc.
 
 **Returns (sync version):** `table` or `fail`
 - `[1, 2, 3, ..., n]` : `table`
@@ -3302,8 +3405,7 @@ Valid hint strings for the keys that take a string:
 
 Equivalent to `getnameinfo(3)`.
 
-When specified, `family` must be one of `"unix"`, `"inet"`, `"inet6"`, `"ipx"`,
-`"netlink"`, `"x25"`, `"ax25"`, `"atmpvc"`, `"appletalk"`, or `"packet"`.
+See [Constants][] for supported address `family` input values.
 
 **Returns (sync version):** `string, string` or `fail`
 
@@ -3413,7 +3515,7 @@ the number to correspond with the table keys used in `uv.thread_getaffinity` and
 
 **Parameters:**
 - `thread`: `luv_thread_t userdata`
-- `priority`: ``number`
+- `priority`: `number`
 
 Sets the specified thread's scheduling priority setting. It requires elevated
 privilege to set specific priorities on some platforms.
@@ -3731,6 +3833,8 @@ table. Each table key is the name of the interface while each associated value
 is an array of address information where fields are `ip`, `family`, `netmask`,
 `internal`, and `mac`.
 
+See [Constants][] for supported address `family` output values.
+
 **Returns:** `table`
 - `[name(s)]` : `table`
   - `ip` : `string`
@@ -3954,3 +4058,4 @@ metrics counters.
 [libuv]: https://github.com/libuv/libuv
 [libuv documentation page]: http://docs.libuv.org/
 [libuv API documentation]: http://docs.libuv.org/en/v1.x/api.html
+[error constants]: https://docs.libuv.org/en/v1.x/errors.html#error-constants

src/constants.c

@@ -321,6 +321,8 @@ static int luv_constants(lua_State* L) {
   lua_pushinteger(L, SIGSYS);
   lua_setfield(L, -2, "SIGSYS");
 #endif
+
+  // Other
 #if LUV_UV_VERSION_GEQ(1, 40, 0)
   lua_pushinteger(L, UV_UDP_MMSG_FREE);
   lua_setfield(L, -2, "UDP_MMSG_FREE");