📝 Improve API documents

Author: Freed-Wu

packages/texcat/lua/texcat.lua

@@ -110,10 +110,12 @@ function M.get_list(list_type, theme_type, syntax_type, theme_names, extensions_
                 if theme_type == 'textmate' then
                     theme = TMTheme { extensions_dir = extensions_dir, name = theme_name }
                     M.themes[theme_name] = theme
+                else
+                    return ''
                 end
             end
-            table.insert(theme_infos, M.themes[theme_name].name)
-            table.insert(theme_infos, tostring(M.themes[theme_name]))
+            table.insert(theme_infos, theme.name)
+            table.insert(theme_infos, tostring(theme))
         end
         list = table.concat(theme_infos, "\n\n")
     end

packages/texcat/lua/texcat/renderer.lua

@@ -1,3 +1,6 @@
+---a class to render
+---@module texcat.renderer
+---@copyright 2025
 ---@diagnostic disable: undefined-global
 -- luacheck: ignore 111 113
 local template = require 'template'
@@ -92,22 +95,6 @@ function M.get_hls(text, captures)
     return hls
 end
 
----@param renderer table?
----@return table renderer
-function M.Renderer:new(renderer)
-    renderer = renderer or {}
-    renderer.theme = renderer.theme or Theme()
-    renderer.syntax = renderer.syntax or Syntax()
-    setmetatable(renderer, {
-        __index = self
-    })
-    return renderer
-end
-
-setmetatable(M.Renderer, {
-    __call = M.Renderer.new
-})
-
 ---escape TeX, protect `\`, `{`, `}`
 ---@param text string
 ---@param prefix string
@@ -155,6 +142,24 @@ function M.escape(text, prefix, math_escape)
     return table.concat(texts, '$')
 end
 
+---@type Renderer
+
+---@param renderer table?
+---@return table renderer
+function M.Renderer:new(renderer)
+    renderer = renderer or {}
+    renderer.theme = renderer.theme or Theme()
+    renderer.syntax = renderer.syntax or Syntax()
+    setmetatable(renderer, {
+        __index = self
+    })
+    return renderer
+end
+
+setmetatable(M.Renderer, {
+    __call = M.Renderer.new
+})
+
 ---get options
 ---@param text string
 ---@param format string

packages/texcat/lua/texcat/syntaxes/tmlanguage.lua

@@ -1,9 +1,14 @@
+---a class to wrap textmate language
+---@module texcat.syntaxes.tmlanguage
+---@copyright 2025
 local T = require 'texcat.themes'
 local textmate = require 'textmate'
 local M = {
     TMLanguage = {}
 }
 
+---@type TMLanguage
+
 ---@param tmlanguage table?
 ---@return table language
 function M.TMLanguage:new(tmlanguage)

packages/texcat/lua/texcat/syntaxes/treesitter.lua

@@ -1,3 +1,6 @@
+---a class to wrap treesitter parsers and queries
+---@module texcat.syntaxes.treesitter
+---@copyright 2025
 local lfs = require 'lfs'
 local ltreesitter = require 'ltreesitter'
 local T = require 'texcat.themes'
@@ -72,24 +75,6 @@ function M.filter_query(code)
     return code
 end
 
----@param treesitter table?
----@return table treesitter
-function M.Treesitter:new(treesitter)
-    treesitter = treesitter or {}
-    treesitter.name = treesitter.name or 'lua'
-    treesitter.extensions_dir = treesitter.extensions_dir or T.get_extensions_dir()
-    treesitter.parser = treesitter.parser or M.require(treesitter.name, treesitter.extensions_dir)
-    treesitter.query = treesitter.query or M.get_syntax(treesitter.parser, treesitter.name, treesitter.extensions_dir)
-    setmetatable(treesitter, {
-        __index = self
-    })
-    return treesitter
-end
-
-setmetatable(M.Treesitter, {
-    __call = M.Treesitter.new
-})
-
 ---add child scopes to color map
 ---@param color_map color_map
 ---@param captures capture[]
@@ -114,7 +99,6 @@ end
 ---@param color_map color_map
 ---@return capture[] captures
 function M.filter_captures(captures, color_map)
-    ---@type capture[]
     local new_captures = {}
     for _, capture in ipairs(captures) do
         if color_map[capture.scope] then
@@ -141,7 +125,6 @@ function M.cut_captures(captures, len)
         end
     end
     ---@alias range {start_index: integer, end_index: integer, scope: string, len: integer}
-    ---@type range[]
     local ranges = {}
     for i = 1, #indices - 1 do
         table.insert(ranges, { start_index = indices[i], end_index = indices[i + 1] - 1, scope = 'source', len = len })
@@ -162,6 +145,26 @@ function M.cut_captures(captures, len)
     return ranges
 end
 
+---@type Treesitter
+
+---@param treesitter table?
+---@return table treesitter
+function M.Treesitter:new(treesitter)
+    treesitter = treesitter or {}
+    treesitter.name = treesitter.name or 'lua'
+    treesitter.extensions_dir = treesitter.extensions_dir or T.get_extensions_dir()
+    treesitter.parser = treesitter.parser or M.require(treesitter.name, treesitter.extensions_dir)
+    treesitter.query = treesitter.query or M.get_syntax(treesitter.parser, treesitter.name, treesitter.extensions_dir)
+    setmetatable(treesitter, {
+        __index = self
+    })
+    return treesitter
+end
+
+setmetatable(M.Treesitter, {
+    __call = M.Treesitter.new
+})
+
 ---capture text as captures according to theme
 ---@param text string
 ---@param theme table

packages/texcat/lua/texcat/themes.lua

@@ -1,4 +1,6 @@
----Some generic utilities for themes
+---some generic utilities for themes
+---@module texcat.themes
+---@copyright 2025
 local lfs = require 'lfs'
 local M = {
     scope_link = {
@@ -26,9 +28,8 @@ end
 
 ---get scope link
 ---@return link link
+---@alias link table<string, string>
 function M.get_scope_link()
-    ---@alias hl_name string
-    ---@type table<hl_name, scope[]>
     local hl_scope_map = {}
     for _, scope_hl in ipairs(require 'nvim-textmate.colormap'.scope_hl_map) do
         local scope, hl = scope_hl[1], scope_hl[2]

packages/texcat/lua/texcat/themes/tmtheme.lua

@@ -1,3 +1,6 @@
+---a class to wrap textmate theme
+---@module texcat.themes.tmtheme
+---@copyright 2025
 local textmate = require 'textmate'
 local T = require 'texcat.themes'
 local M = {
@@ -12,16 +15,19 @@ function M.load_extensions_dir(extensions_dir)
     end
 end
 
+---@type TMTheme
+
 ---@param tmtheme table?
 ---@return table theme
 function M.TMTheme:new(tmtheme)
     tmtheme = tmtheme or {}
     tmtheme.extensions_dir = tmtheme.extensions_dir or T.get_extensions_dir()
     M.load_extensions_dir(tmtheme.extensions_dir)
-    tmtheme.name = tmtheme.name or textmate.highlight_themes()[1][1]
+    local themes = textmate.highlight_themes() or {{''}}
+    tmtheme.name = tmtheme.name or themes[1][1]
     tmtheme.id = tmtheme.id or textmate.highlight_load_theme(tmtheme.name)
     setmetatable(tmtheme, {
-        __tostring = M.TMTheme.list_colors,
+        __tostring = self.list_colors,
         __index = self
     })
     return tmtheme
@@ -41,7 +47,6 @@ function M.TMTheme.get_color_map()
     for k, v in ipairs(theme) do
         theme[k] = math.floor(v)
     end
-    ---@type color_map
     local color_map = {}
     -- FIXME: https://github.com/icedman/nvim-textmate/issues/10
     -- color_map.source = { theme[1], theme[2], theme[3] }