feat(doc): move to structured format

This change introduces the files `docs.lua` and `docgen.lua`
which are used to generate `docs.md`.

`docs.lua` use a bespoke format designed so it can emit the `docs.md`
as close to the original version.

`docgen.lua` takes `docs.lua` as an input an emits `docs.md`.

To regenerate the `docs.md`, simply run `lua docgen.lua`.

Closes #632

Author: lewis6991

.gitattributes

@@ -0,0 +1,2 @@
+docs.md linguist-documentation
+docs.md linguist-generated

docgen.lua

@@ -0,0 +1,391 @@
+local doctypes = require('docs')
+local doc = doctypes[1]
+local types = doctypes[2]
+
+--- @param str string
+--- @return string
+local function dedent(str)
+  local prefix = 99
+
+  str = str:gsub('^\n', ''):gsub('%s+$', '')
+
+  for line in str:gmatch('[^\n]+') do
+    local s, e = line:find('^%s*')
+    local amount = (e - s) + 1
+    if amount < prefix then
+      prefix = amount
+    end
+  end
+
+  local result = {} --- @type string[]
+  for line in str:gmatch('([^\n]*)\n?') do
+    result[#result + 1] = line:sub(prefix + 1)
+  end
+
+  local ret = table.concat(result, '\n')
+  ret = ret:gsub('\n+$', '')
+
+  return ret
+end
+
+--- @param lvl integer
+--- @param str string
+--- @return string
+local function heading(lvl, str)
+  return string.rep('#', lvl) .. ' ' .. str:gsub(' %- ', ' — ')
+end
+
+--- @param ty Doc.Type
+--- @return boolean
+local function isoptional(ty)
+  if type(ty) == 'string' then
+    return ty == 'nil'
+  end
+  if ty.kind == 'union' then
+    for _, uty in ipairs(ty[1]) do
+      if isoptional(uty) then
+        return true
+      end
+    end
+  end
+  return false
+end
+
+--- @param method Doc.Method
+--- @return string
+local function sig(method)
+  local args = {} --- @type string[]
+  for _, param in ipairs(method.params or {}) do
+    local nm = param.name
+    if isoptional(param.type) then
+      nm = '[' .. nm .. ']'
+    end
+    args[#args + 1] = nm
+  end
+  return ('`uv.%s(%s)`'):format(method.name, table.concat(args, ', '))
+end
+
+local function pad(lvl)
+  return string.rep(' ', lvl * 2)
+end
+
+local normty
+
+--- @param ty Doc.Type.Fun
+--- @param lvl? integer
+--- @param desc? string
+--- @return string
+local function normtyfun(ty, lvl, desc)
+  local r = {} --- @type string[]
+  r[#r + 1] = '`callable`'
+  if desc then
+    r[#r] = r[#r] .. ' ' .. desc
+  end
+  for _, arg in ipairs(ty.args) do
+    local arg_nm, arg_ty, arg_desc = arg[1], arg[2], arg[3]
+    if arg_nm == 'err' then
+      arg_ty = 'nil|string'
+    end
+    r[#r + 1] = ('%s- `%s`: %s'):format(pad(lvl), arg_nm, normty(arg_ty, lvl + 1))
+    if arg_desc then
+      r[#r] = r[#r] .. ' ' .. arg_desc
+    end
+  end
+
+  return table.concat(r, '\n')
+end
+
+--- @param ty Doc.Type.Table
+--- @param lvl? integer
+--- @param desc? string
+--- @return string
+local function normtytbl(ty, lvl, desc)
+  local r = {} --- @type string[]
+  r[#r + 1] = '`table`'
+  if desc then
+    r[#r] = r[#r] .. ' ' .. desc
+  end
+  for _, field in ipairs(ty.fields) do
+    local name, aty, default, adesc = field[1], field[2], field[3], field[4]
+    r[#r + 1] = ('%s- `%s`: %s'):format(pad(lvl), name, normty(aty, lvl + 1, adesc))
+    if default then
+      r[#r] = ('%s (default: `%s`)'):format(r[#r], default)
+    end
+  end
+
+  return table.concat(r, '\n')
+end
+
+--- @param ty string
+--- @param _lvl? integer
+--- @param desc? string
+--- @return string
+local function normtystr(ty, _lvl, desc)
+  do -- TODO(lewis6991): remove
+    if ty == 'uv_handle_t' or ty == 'uv_req_t' or ty == 'uv_stream_t' then
+      return '`userdata` for sub-type of `' .. ty .. '`'
+    end
+    ty = ty:gsub('uv_[a-z_]+', '%0 userdata')
+    ty = ty:gsub('%|', '` or `')
+  end
+
+  local desc_str = desc and ' ' .. desc or ''
+  return '`' .. ty .. '`' .. desc_str
+end
+
+--- @param ty Doc.Type.Dict
+--- @param lvl? integer
+--- @param desc? string
+--- @return string
+local function normtydict(ty, lvl, desc)
+  local r = {} --- @type string[]
+  r[#r + 1] = '`table`'
+  if desc then
+    r[#r] = r[#r] .. ' ' .. desc
+  end
+  -- TODO(lewis6991): remove
+  if ty.key == 'integer' then
+    ty.key = '1, 2, 3, ..., n'
+  end
+  r[#r + 1] = ('%s- `[%s]`: %s'):format(pad(lvl), ty.key, normty(ty.value, lvl + 1))
+  return table.concat(r, '\n')
+end
+
+--- @param ty Doc.Type.Union
+--- @param lvl? integer
+--- @param desc? string
+--- @return string
+local function normtyunion(ty, lvl, desc)
+  local tys = ty[1]
+
+  local r = {} --- @type string[]
+
+  local main_ty --- @type integer?
+  for i, uty in ipairs(tys) do
+    if normty(uty):match('\n') then
+      main_ty = i
+    end
+    r[#r + 1] = normty(uty, lvl, i == #tys and desc or nil)
+  end
+
+  if main_ty and #tys > 1 then
+    local others = {} --- @type string[]
+    for i, oty in ipairs(r) do
+      if i ~= main_ty then
+        others[#others + 1] = oty
+      end
+    end
+    local other_ty_str = table.concat(others, ' or ')
+    -- local other_ty_str = table.concat(others, '|')
+
+    return (r[main_ty]:gsub('\n', ' or ' .. other_ty_str .. '\n', 1))
+  end
+
+  return table.concat(r, ' or ')
+  -- return table.concat(r, '|')
+end
+
+local types_noinline = {
+  threadargs = true,
+  buffer = true,
+}
+
+--- @param ty Doc.Type
+--- @param lvl? integer
+--- @param desc? string
+--- @return string
+function normty(ty, lvl, desc)
+  -- resolve type
+  if types[ty] and not types_noinline[ty] and not types[ty].extends then
+    ty = types[ty]
+  end
+  lvl = lvl or 0
+  local f --- @type fun(ty: Doc.Type, lvl: integer, desc: string): string
+  if type(ty) == 'string' then
+    f = normtystr
+  elseif ty.kind == 'function' then
+    f = normtyfun
+  elseif ty.kind == 'table' then
+    f = normtytbl
+  elseif ty.kind == 'dict' then
+    f = normtydict
+  elseif ty.kind == 'union' then
+    f = normtyunion
+  end
+  return f(ty, lvl, desc)
+end
+
+--- @param out file*
+--- @param param Doc.Method.Param
+local function write_param(out, param)
+  out:write(('- `%s`:'):format(param.name))
+  local ty = param.type
+  if ty then
+    out:write(' ', normty(ty, 1, param.desc))
+  elseif param.desc then
+    out:write(' ', param.desc)
+  end
+  if param.default then
+    out:write((' (default: `%s`)'):format(param.default))
+  end
+  out:write('\n')
+end
+
+--- @param ty Doc.Type
+local function remove_nil(ty)
+  if type(ty) == 'table' and ty.kind == 'union' then
+    for i, uty in ipairs(ty[1]) do
+      if uty == 'nil' then
+        table.remove(ty[1], i)
+        break
+      else
+        remove_nil(uty)
+      end
+    end
+  end
+end
+
+--- @param out file*
+--- @param x string|Doc.Method.Return[]
+--- @param variant? string
+local function write_return(out, x, variant)
+  local variant_str = variant and (' (%s version)'):format(variant) or ''
+  if type(x) == 'string' then
+    out:write(('**Returns%s:** %s\n'):format(variant_str, normty(x)))
+  elseif type(x) == 'table' then
+    if x[2] and x[2][2] == 'err' and x[3] and x[3][2] == 'err_name' then
+      local sty = x[1][1]
+      remove_nil(sty)
+      local rty = normty(sty, nil, 'or `fail`')
+      out:write(('**Returns%s:** %s\n\n'):format(variant_str, rty))
+      return
+    else
+      local tys = {} --- @type string[]
+      for _, ret in ipairs(x) do
+        tys[#tys + 1] = normty(ret[1])
+      end
+      out:write(('**Returns%s:** %s\n'):format(variant_str, table.concat(tys, ', ')))
+    end
+  else
+    out:write('**Returns:** Nothing.\n')
+  end
+  out:write('\n')
+end
+
+--- @param out file*
+--- @param method Doc.Method
+--- @param lvl integer
+local function write_method(out, method, lvl)
+  out:write(heading(lvl, sig(method)))
+  out:write('\n\n')
+
+  if method.method_form then
+    out:write(('> method form `%s`\n\n'):format(method.method_form))
+  end
+
+  if method.deprecated then
+    out:write('**Deprecated:** ', dedent(method.deprecated))
+    out:write('\n\n')
+    return
+  end
+
+  if method.params then
+    out:write('**Parameters:**\n')
+    for _, param in ipairs(method.params) do
+      write_param(out, param)
+    end
+    out:write('\n')
+  end
+
+  if method.desc then
+    out:write(dedent(method.desc))
+    out:write('\n\n')
+  end
+
+  if method.returns_doc then
+    out:write('**Returns:**')
+    local r = dedent(method.returns_doc)
+    if r:sub(1, 1) == '-' then
+      out:write('\n')
+    else
+      out:write(' ')
+    end
+    out:write(r)
+    out:write('\n')
+    out:write('\n')
+  elseif method.returns_sync and method.returns_async then
+    write_return(out, method.returns_sync, 'sync')
+    write_return(out, method.returns_async, 'async')
+  else
+    write_return(out, method.returns)
+  end
+
+  if method.example then
+    out:write(dedent(method.example))
+    out:write('\n\n')
+  end
+
+  if method.see then
+    out:write(('See [%s][].\n\n'):format(method.see))
+  end
+
+  for _, note in ipairs(method.notes or {}) do
+    local notes = dedent(note)
+    out:write('**Note**:')
+    if notes:sub(1, 3) == '1. ' then
+      out:write('\n', notes, '\n\n')
+    else
+      out:write(' ', notes, '\n\n')
+    end
+  end
+
+  for _, warn in ipairs(method.warnings or {}) do
+    out:write(('**Warning**: %s\n\n'):format(dedent(warn)))
+  end
+
+  if method.since then
+    out:write(('**Note**: New in libuv version %s.\n\n'):format(method.since))
+  end
+end
+
+--- @param out file*
+--- @param section Doc
+--- @param lvl integer
+local function write_section(out, section, lvl)
+  local title = section.title
+  if title then
+    out:write(heading(lvl, title))
+    out:write('\n\n')
+  end
+  local id = section.id
+  if id then
+    local tag = assert(title):match('^`[a-z_]+`') or title
+    out:write(('[%s]: #%s\n\n'):format(tag, id))
+  end
+
+  if section.desc then
+    out:write(dedent(section.desc))
+    out:write('\n\n')
+  end
+
+  if section.constants then
+    for _, constant in ipairs(section.constants) do
+      out:write(('- `%s`: "%s"\n'):format(constant[1], constant[2]))
+    end
+    out:write('\n')
+  end
+
+  for _, method in ipairs(section.methods or {}) do
+    write_method(out, method, lvl + 1)
+  end
+
+  for _, subsection in ipairs(section.sections or {}) do
+    write_section(out, subsection, lvl + 1)
+  end
+end
+
+local out = assert(io.open('docs.md', 'w'))
+
+for _, section in ipairs(doc) do
+  write_section(out, section, 1)
+end