From a5fe8f59d98398d04bed8586cee73864bbcdde92 Mon Sep 17 00:00:00 2001
From: Lewis Russell <lewis6991@gmail.com>
Date: Tue, 27 Feb 2024 15:20:32 +0000
Subject: 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.
---
 runtime/lua/vim/_meta/builtin.lua | 1 +
 runtime/lua/vim/_meta/lpeg.lua    | 2 ++
 runtime/lua/vim/_meta/regex.lua   | 1 +
 3 files changed, 4 insertions(+)

(limited to 'runtime/lua/vim/_meta')

diff --git a/runtime/lua/vim/_meta/builtin.lua b/runtime/lua/vim/_meta/builtin.lua
index 472162ecc1..4831989e1a 100644
--- a/runtime/lua/vim/_meta/builtin.lua
+++ b/runtime/lua/vim/_meta/builtin.lua
@@ -61,6 +61,7 @@ error('Cannot require a meta file')
 ---
 --- </pre>
 
+---@nodoc
 ---@class vim.NIL
 
 ---@type vim.NIL
diff --git a/runtime/lua/vim/_meta/lpeg.lua b/runtime/lua/vim/_meta/lpeg.lua
index 202c99f18c..1ce40f3340 100644
--- a/runtime/lua/vim/_meta/lpeg.lua
+++ b/runtime/lua/vim/_meta/lpeg.lua
@@ -21,6 +21,7 @@ error('Cannot require a meta file')
 
 vim.lpeg = {}
 
+--- @nodoc
 --- @class vim.lpeg.Pattern
 --- @operator unm: vim.lpeg.Pattern
 --- @operator add(vim.lpeg.Pattern): vim.lpeg.Pattern
@@ -167,6 +168,7 @@ function vim.lpeg.S(string) end
 --- @return vim.lpeg.Pattern
 function vim.lpeg.V(v) end
 
+--- @nodoc
 --- @class vim.lpeg.Locale
 --- @field alnum userdata
 --- @field alpha userdata
diff --git a/runtime/lua/vim/_meta/regex.lua b/runtime/lua/vim/_meta/regex.lua
index ab403b97e7..595ad96319 100644
--- a/runtime/lua/vim/_meta/regex.lua
+++ b/runtime/lua/vim/_meta/regex.lua
@@ -12,6 +12,7 @@
 --- @return vim.regex
 function vim.regex(re) end
 
+--- @nodoc
 --- @class vim.regex
 local regex = {} -- luacheck: no unused
 
-- 
cgit