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, 39 insertions, 20 deletions

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)