docs: improve/add documentation of Lua types

- Added `@inlinedoc` so single use Lua types can be inlined into the
  functions docs. E.g.

  ```lua
  --- @class myopts
  --- @inlinedoc
  ---
  --- Documentation for some field
  --- @field somefield integer

  --- @param opts myOpts
  function foo(opts)
  end
  ```

  Will be rendered as

  ```
  foo(opts)

    Parameters:
      - {opts} (table) Object with the fields:
               - somefield (integer) Documentation
                 for some field
  ```

- Marked many classes with with `@nodoc` or `(private)`.
  We can eventually introduce these when we want to.

2 files changed, 145 insertions, 20 deletions

diff --git a/test/functional/script/luacats_parser_spec.lua b/test/functional/script/luacats_parser_spec.lua
new file mode 100644
index 0000000000..e10aa81003
--- /dev/null
+++ b/test/functional/script/luacats_parser_spec.lua
@@ -0,0 +1,106 @@
+local helpers = require('test.functional.helpers')(after_each)
+local eq = helpers.eq
+
+local parser = require('scripts/luacats_parser')
+
+--- @param name string
+--- @param text string
+--- @param exp table<string,string>
+local function test(name, text, exp)
+  exp = vim.deepcopy(exp, true)
+  it(name, function()
+    eq(exp, parser.parse_str(text, 'myfile.lua'))
+  end)
+end
+
+describe('luacats parser', function()
+  local exp = {
+    myclass = {
+      kind = 'class',
+      module = 'myfile.lua',
+      name = 'myclass',
+      fields = {
+        { kind = 'field', name = 'myclass', type = 'integer' },
+      },
+    },
+  }
+
+  test(
+    'basic class',
+    [[
+    --- @class myclass
+    --- @field myclass integer
+  ]],
+    exp
+  )
+
+  exp.myclass.inlinedoc = true
+
+  test(
+    'class with @inlinedoc (1)',
+    [[
+    --- @class myclass
+    --- @inlinedoc
+    --- @field myclass integer
+  ]],
+    exp
+  )
+
+  test(
+    'class with @inlinedoc (2)',
+    [[
+    --- @inlinedoc
+    --- @class myclass
+    --- @field myclass integer
+  ]],
+    exp
+  )
+
+  exp.myclass.inlinedoc = nil
+  exp.myclass.nodoc = true
+
+  test(
+    'class with @nodoc',
+    [[
+    --- @nodoc
+    --- @class myclass
+    --- @field myclass integer
+  ]],
+    exp
+  )
+
+  exp.myclass.nodoc = nil
+  exp.myclass.access = 'private'
+
+  test(
+    'class with (private)',
+    [[
+    --- @class (private) myclass
+    --- @field myclass integer
+  ]],
+    exp
+  )
+
+  exp.myclass.fields[1].desc = 'Field\ndocumentation'
+
+  test(
+    'class with field doc above',
+    [[
+    --- @class (private) myclass
+    --- Field
+    --- documentation
+    --- @field myclass integer
+  ]],
+    exp
+  )
+
+  exp.myclass.fields[1].desc = 'Field documentation'
+  test(
+    'class with field doc inline',
+    [[
+    --- @class (private) myclass
+    --- @field myclass integer Field documentation
+  ]],
+    exp
+  )
+end)
diff --git a/test/functional/script/text_utils_spec.lua b/test/functional/script/text_utils_spec.lua
index c429d306d5..e644df92ae 100644
--- a/test/functional/script/text_utils_spec.lua
+++ b/test/functional/script/text_utils_spec.lua
@@ -2,18 +2,28 @@ local helpers = require('test.functional.helpers')(after_each)
 local exec_lua = helpers.exec_lua
 local eq = helpers.eq
 
-local function md_to_vimdoc(text)
+local function md_to_vimdoc(text, start_indent, indent, text_width)
   return exec_lua(
     [[
+    local text, start_indent, indent, text_width = ...
+    start_indent = start_indent or 0
+    indent = indent or 0
+    text_width = text_width or 70
     local text_utils = require('scripts/text_utils')
-    return text_utils.md_to_vimdoc(table.concat(..., '\n'), 0, 0, 70)
+    return text_utils.md_to_vimdoc(table.concat(text, '\n'), start_indent, indent, text_width)
   ]],
-    text
+    text,
+    start_indent,
+    indent,
+    text_width
   )
 end
 
-local function test(act, exp)
-  eq(table.concat(exp, '\n'), md_to_vimdoc(act))
+local function test(what, act, exp, ...)
+  local argc, args = select('#', ...), { ... }
+  it(what, function()
+    eq(table.concat(exp, '\n'), md_to_vimdoc(act, unpack(args, 1, argc)))
+  end)
 end
 
 describe('md_to_vimdoc', function()
@@ -21,19 +31,28 @@ describe('md_to_vimdoc', function()
     helpers.clear()
   end)
 
-  it('can render para after fenced code', function()
-    test({
-      '- Para1',
-      '  ```',
-      '  code',
-      '  ```',
-      '  Para2',
-    }, {
-      '• Para1 >',
-      '    code',
-      '<',
-      '  Para2',
-      '',
-    })
-  end)
+  test('can render para after fenced code', {
+    '- Para1',
+    '  ```',
+    '  code',
+    '  ```',
+    '  Para2',
+  }, {
+    '• Para1 >',
+    '    code',
+    '<',
+    '  Para2',
+    '',
+  })
+
+  test('start_indent only applies to first line', {
+    'para1',
+    '',
+    'para2',
+  }, {
+    'para1',
+    '',
+    '          para2',
+    '',
+  }, 0, 10, 78)
 end)