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.

1 files changed, 106 insertions, 0 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)