Update and expand docs

[SinisterRectus]

First pass at improving docs.md.

Closes #118
Closes #144
Closes #378

This is a total rewrite so the diff might be overwhelming. Sorry that it's all one big commit. Since the previous version, I cleaned up or expanded the existing sections and added:

• Error handling
• Version checking
• uv_fs_event_t
• uv_fs_poll_t
• File system operations
• Thread pool work scheduling
• DNS utility functions
• Threading and synchronization utilities
• Miscellaneous utilities

TODO

• new_udp and new_tcp flags - Documented.
  • New change; haven't had a chance to look at it.
• translate_sys_error - Ignored.
  • This is the first error function exposed to Lua, so I'm not sure what this is doing here.
• uv_req_t - Documented.
  • We only expose uv_cancel but we might want to document which subtypes are uv_req_t and which ones can be canceled. (See uv.cancel #416)
• tcp_write_queue_size - Deprecated.
  • This isn't a libuv function, so I'm not sure what it's doing.
• tcp_close_reset - Documented.
  • Returned values are unclear to me.
• fs_readdir - Documented.
  • Behavior compared to fs_scandir_next is unclear to me.
• Parameter types (maybe) - Deferred
  • I documented return types, but not parameters. This is going to be a bit of work, so I may save it for another time.

[squeek502]

Comments on the TODOs:

• new_udp and new_tcp: see Some minor API inconsistencies #399 (comment)
• translate_sys_error: This was made public in Libuv in 1.10.0, and is the only public Libuv error function, which explains why its the only one bound. How its bound is interesting: it returns the err, name portion of the fail tuple, so I guess it would enable constructing a compatible fail return from Lua (return nil, uv.translate_sys_error(SOME_ERR_CODE_THAT_COMES_FROM_CALLING_A_SYSTEM_FUNCTION))
• tcp_write_queue_size: Looks like uv_stream_get_write_queue_size got added in 1.19.0 but Luv never bound it. I'll create a new issue for all unbound functions that remain. EDIT: Remaining unbound functions #410
• tcp_close_reset: Looks like a bug, it returns whatever argument happens to be at the top of the stack (usually the callback or the uv_tcp_t) EDIT: Fix tcp_close_reset returning inconsistent values on success #411
• fs_readdir: It is non-blocking whereas fs_scandir_next is blocking. Example:

local uv = require('luv')

local check = uv.new_check()
uv.check_start(check, function()
  print('loop iteration')
end)

uv.fs_scandir('.', function(err, req)
  assert(not err, err)
  while true do
    local name, ftype = uv.fs_scandir_next(req)
    if not name then break end
    print(name, ftype)
  end
  uv.check_stop(check)
end)

uv.run()

prints:

loop iteration
.ci     directory
.editorconfig   file
.git    directory
.gitignore      file
.gitmodules     file
...

whereas:

local uv = require('luv')
local dump = require('lib/utils').dump

local check = uv.new_check()
uv.check_start(check, function()
  print('loop iteration')
end)

uv.fs_opendir('.', function(err, dir)
  assert(not err, err)

  local function readdir_cb(err, files)
    assert(not err, err)
    if files then
      print(dump(files))
      uv.fs_readdir(dir, readdir_cb)
    else
      assert(uv.fs_closedir(dir))
      uv.check_stop(check)
    end
  end

  uv.fs_readdir(dir, readdir_cb)
end)

uv.run()

prints:

loop iteration
loop iteration
{ { name = ".ci", type = "directory" } }
loop iteration
loop iteration
{ { name = ".editorconfig", type = "file" } }
loop iteration
loop iteration
{ { name = ".git", type = "directory" } }
loop iteration
loop iteration
{ { name = ".gitignore", type = "file" } }
loop iteration
{ { name = ".gitmodules", type = "file" } }
loop iteration
...

[squeek502]

I was wrong about uv_translate_sys_error being the only public Libuv error function. All the functions here are just as public.

[SinisterRectus]

Most of the remaining sections are now done.

I am going to ignore translate_sys_error for now, as #400 and #410 are still being considered.

I added deprecation notices for uv.getpid and uv.tcp_write_queue_size.

I am going to defer documenting parameter types until a later date, if done at all. With the parameter names and function description, there is usually enough information to figure out the type (as in the Lua reference manual), but sometimes a table is nice at a glance:

uv.timer_start(timer, timeout, repeat, callback)

Parameter	Type
timer	uv_timer_t
timeout	integer
repeat	integer
callback	function

If timeout is zero, the callback fires on the next event loop iteration. If
repeat is non-zero, the callback fires first after timeout milliseconds and
then repeatedly after repeat milliseconds.

[squeek502]

Looks good, nice work. 👍

I think another way to improve them is to make sure all functions with callbacks specify what arguments the callbacks are called with, but that can be done later.

[zhaozg]

Thanks you nice job.