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/treesitter/language.lua | 20 +++++++++++---------
 1 file changed, 11 insertions(+), 9 deletions(-)

(limited to 'runtime/lua/vim/treesitter/language.lua')

diff --git a/runtime/lua/vim/treesitter/language.lua b/runtime/lua/vim/treesitter/language.lua
index 0f6d5ecbd0..78c73c698c 100644
--- a/runtime/lua/vim/treesitter/language.lua
+++ b/runtime/lua/vim/treesitter/language.lua
@@ -56,10 +56,17 @@ function M.require_language(lang, path, silent, symbol_name)
   return true
 end
 
----@class vim.treesitter.language.RequireLangOpts
----@field path? string
----@field silent? boolean
+---@class vim.treesitter.language.add.Opts
+---@inlinedoc
+---
+---Default filetype the parser should be associated with.
+---(Default: {lang})
 ---@field filetype? string|string[]
+---
+---Optional path the parser is located at
+---@field path? string
+---
+---Internal symbol name for the language to load
 ---@field symbol_name? string
 
 --- Load parser with name {lang}
@@ -67,13 +74,8 @@ end
 --- Parsers are searched in the `parser` runtime directory, or the provided {path}
 ---
 ---@param lang string Name of the parser (alphanumerical and `_` only)
----@param opts (table|nil) Options:
----                        - filetype (string|string[]) Default filetype the parser should be associated with.
----                          Defaults to {lang}.
----                        - path (string|nil) Optional path the parser is located at
----                        - symbol_name (string|nil) Internal symbol name for the language to load
+---@param opts? vim.treesitter.language.add.Opts Options:
 function M.add(lang, opts)
-  ---@cast opts vim.treesitter.language.RequireLangOpts
   opts = opts or {}
   local path = opts.path
   local filetype = opts.filetype or lang
-- 
cgit