From f47abd169113f9412625af38349e79ef82f05efc Mon Sep 17 00:00:00 2001
From: JuanZoran <1430359574@qq.com>
Date: Tue, 14 Mar 2023 22:30:25 +0800
Subject: [PATCH] fix: more lsp info comment and fix backend opts error

---
 lua/Trans/backend/baidu.lua          | 54 ++++++++++++++++++++--------
 lua/Trans/backend/offline.lua        | 11 ++++++
 lua/Trans/core/backend.lua           |  3 +-
 lua/Trans/core/buffer.lua            |  6 ++--
 lua/Trans/core/conf.lua              |  2 +-
 lua/Trans/core/data.lua              |  2 +-
 lua/Trans/core/frontend.lua          |  2 +-
 lua/Trans/core/translate.lua         |  2 +-
 lua/Trans/core/util.lua              |  6 ++--
 lua/Trans/core/window.lua            |  7 ++++
 lua/Trans/frontend/hover/execute.lua |  2 ++
 lua/Trans/frontend/hover/init.lua    | 37 +++++++++----------
 lua/Trans/frontend/hover/load.lua    |  6 +++-
 lua/Trans/init.lua                   |  8 +++--
 lua/Trans/util/md5.lua               |  4 +++
 15 files changed, 102 insertions(+), 50 deletions(-)

diff --git a/lua/Trans/backend/baidu.lua b/lua/Trans/backend/baidu.lua
index de53ac4..7764c75 100644
--- a/lua/Trans/backend/baidu.lua
+++ b/lua/Trans/backend/baidu.lua
@@ -1,3 +1,9 @@
+---@class Baidu: TransBackend
+---@field uri string api uri
+---@field salt string
+---@field app_id string
+---@field app_passwd string
+---@field disable boolean
 local M = {
     uri  = 'https://fanyi-api.baidu.com/api/trans/vip/translate',
     salt = tostring(math.random(bit.lshift(1, 15))),
@@ -6,6 +12,19 @@ local M = {
 
 local Trans = require('Trans')
 
+
+---@class BaiduQuery
+---@field q string
+---@field from string
+---@field to string
+---@field appid string
+---@field salt string
+---@field sign string
+
+
+---Get content for query
+---@param data TransData
+---@return BaiduQuery
 function M.get_content(data)
     local tmp  = M.app_id .. data.str .. M.salt .. M.app_passwd
     local sign = Trans.util.md5.sumhexa(tmp)
@@ -27,7 +46,9 @@ end
 --   status = 200
 -- }
 
-
+---@overload fun(TransData): TransResult
+---Query Using Baidu API
+---@param data TransData
 function M.query(data)
     if M.disable then
         data.result.baidu = false
@@ -37,22 +58,23 @@ function M.query(data)
 
     local handle = function(res)
         local status, body = pcall(vim.json.decode, res.body)
-        if status and body then
-            local result = body.trans_result
-            if result then
-                -- TEST :whether multi result
-                assert(#result == 1)
-                result = result[1]
-                data.result.baidu = {
-                    ['title'] = result.src,
-                    [data.from == 'en' and 'translation' or 'definition'] = result.dst,
-                }
-                return
-            end
+        if not status or not body then
+            data.result.baidu = false
+            data.trace = res
+            return
         end
 
-        data.result.baidu = false
-        data.trace = res
+
+        local result = body.trans_result
+        if result then
+            -- TEST :whether multi result
+            assert(#result == 1)
+            result = result[1]
+            data.result.baidu = {
+                ['title'] = result.src,
+                [data.from == 'en' and 'translation' or 'definition'] = result.dst,
+            }
+        end
     end
 
 
@@ -62,6 +84,8 @@ function M.query(data)
     })
 end
 
+---@class TransBackend
+---@field baidu Baidu
 return M
 
 -- -- NOTE :free tts:
diff --git a/lua/Trans/backend/offline.lua b/lua/Trans/backend/offline.lua
index 4f84382..a8e7613 100644
--- a/lua/Trans/backend/offline.lua
+++ b/lua/Trans/backend/offline.lua
@@ -1,8 +1,10 @@
+---@class Offline: TransBackend
 local M = {
     no_wait = true,
     name = 'offline',
 }
 
+
 local db = require 'sqlite.db'
 vim.api.nvim_create_autocmd('VimLeavePre', {
     once = true,
@@ -13,6 +15,10 @@ vim.api.nvim_create_autocmd('VimLeavePre', {
     end
 })
 
+
+---@param data any
+---@return any
+---@overload fun(TransData): TransResult
 function M.query(data)
     if data.is_word == false or data.from == 'zh' then return end
 
@@ -48,6 +54,7 @@ local function exist(str)
     return str and str ~= ''
 end
 
+---@type (fun(res):any)[]
 local formatter = {
     title = function(res)
         local title = {
@@ -152,6 +159,9 @@ local formatter = {
     end,
 }
 
+---Formater for TransResul
+---@param res TransResult
+---@return TransResult
 function M.formatter(res)
     for field, func in pairs(formatter) do
         res[field] = func(res)
@@ -160,4 +170,5 @@ function M.formatter(res)
     return res
 end
 
+
 return M
diff --git a/lua/Trans/core/backend.lua b/lua/Trans/core/backend.lua
index e323f72..1ffdb5b 100644
--- a/lua/Trans/core/backend.lua
+++ b/lua/Trans/core/backend.lua
@@ -4,6 +4,8 @@ local Trans = require('Trans')
 ---@class TransBackend
 ---@field query fun(TransData): TransResult
 ---@field opts TransBackendOpts
+---@field no_wait? boolean whether need to wait for the result
+---@field name string @backend name
 
 
 local conf = Trans.conf
@@ -22,7 +24,6 @@ end
 local default_opts = conf.backend.default
 default_opts.__index = default_opts
 
-
 ---@class Trans
 ---@field backend table<string, TransBackend>
 return setmetatable({}, {
diff --git a/lua/Trans/core/buffer.lua b/lua/Trans/core/buffer.lua
index 16248b9..25120dd 100644
--- a/lua/Trans/core/buffer.lua
+++ b/lua/Trans/core/buffer.lua
@@ -92,12 +92,12 @@ end
 
 ---Add highlight to buffer
 ---@param linenr number line number should be set[one index]
----@param col_start number column start [zero index]
----@param col_end number column end
 ---@param hl_group string highlight group
+---@param col_start? number column start [zero index]
+---@param col_end? number column end
 ---@param ns number? highlight namespace
 function buffer:add_highlight(linenr, hl_group, col_start, col_end, ns)
-    linenr = linenr and linenr - 1 or -1
+    linenr = linenr - 1 or -1
     col_start = col_start or 0
     api.nvim_buf_add_highlight(self.bufnr, ns or -1, hl_group, linenr, col_start, col_end or -1)
 end
diff --git a/lua/Trans/core/conf.lua b/lua/Trans/core/conf.lua
index d6dc4dc..f269609 100644
--- a/lua/Trans/core/conf.lua
+++ b/lua/Trans/core/conf.lua
@@ -48,7 +48,7 @@ return {
                 interval = 12,
             },
         },
-        ---@class HoverOptions : TransFrontendOpts
+        ---@class TransHoverOpts : TransFrontendOpts
         hover = {
             ---@type integer Max Width of Hover Window
             width             = 37,
diff --git a/lua/Trans/core/data.lua b/lua/Trans/core/data.lua
index 5a5bd83..e82e2ff 100644
--- a/lua/Trans/core/data.lua
+++ b/lua/Trans/core/data.lua
@@ -7,7 +7,7 @@ local Trans = require('Trans')
 ---@field is_word boolean @Is the str a word
 ---@field str string @The original string
 ---@field mode string @The mode of the str
----@field result table<string, TransResult> @The result of the translation
+---@field result table<string, TransResult|boolean> @The result of the translation
 ---@field frontend TransFrontend
 ---@field backends table<string, TransBackend>
 local M = {}
diff --git a/lua/Trans/core/frontend.lua b/lua/Trans/core/frontend.lua
index cb8a83b..a588bf7 100644
--- a/lua/Trans/core/frontend.lua
+++ b/lua/Trans/core/frontend.lua
@@ -26,7 +26,7 @@ end
 ---@class TransFrontend
 ---@field opts TransFrontendOpts
 ---@field get_active_instance fun():TransFrontend?
----@field process fun(data: TransData, result: TransResult)
+---@field process fun(self: TransFrontend, data: TransData, result: TransResult)
 ---@field wait fun(self: TransFrontend, result: TransResult, name: string, timeout: integer)
 ---@field execute fun(action: string) @Execute action for frontend instance
 
diff --git a/lua/Trans/core/translate.lua b/lua/Trans/core/translate.lua
index b55e8f1..1328d47 100644
--- a/lua/Trans/core/translate.lua
+++ b/lua/Trans/core/translate.lua
@@ -27,7 +27,7 @@ local function do_query(data)
             backend.query(data)
         else
             backend.query(data)
-            frontend:wait(result, name, backend.timeout)
+            frontend:wait(result, name, backend.opts.timeout)
         end
 
 
diff --git a/lua/Trans/core/util.lua b/lua/Trans/core/util.lua
index f26df32..b2656fa 100644
--- a/lua/Trans/core/util.lua
+++ b/lua/Trans/core/util.lua
@@ -1,5 +1,3 @@
----@class Trans
----@field util TransUtil
 local Trans = require('Trans')
 
 local fn, api = vim.fn, vim.api
@@ -79,4 +77,6 @@ function M.is_English(str)
     return true
 end
 
-Trans.util = M
+---@class Trans
+---@field util TransUtil
+return M
diff --git a/lua/Trans/core/window.lua b/lua/Trans/core/window.lua
index 2227ba0..52a9777 100644
--- a/lua/Trans/core/window.lua
+++ b/lua/Trans/core/window.lua
@@ -169,11 +169,15 @@ end
 window.__index = window
 
 
+---@alias WindowOpts
+---|{style: string, border: string, focusable: boolean, noautocmd?: boolean, relative: string, width: integer, height: integer, col: integer, row: integer, zindex?: integer, title?: table | string}
+
 
 ---@class TransWindowOpts
 local default_opts = {
     enter    = false,
     winid    = -1,
+    ---@type WindowOpts
     win_opts = {
         style     = 'minimal',
         border    = 'rounded',
@@ -182,6 +186,9 @@ local default_opts = {
     },
 }
 
+
+
+
 ---@class TransWindow
 ---@field buffer TransBuffer attached buffer object
 ---@field win_opts table window config [**When open**]
diff --git a/lua/Trans/frontend/hover/execute.lua b/lua/Trans/frontend/hover/execute.lua
index c0c1f54..745dd84 100644
--- a/lua/Trans/frontend/hover/execute.lua
+++ b/lua/Trans/frontend/hover/execute.lua
@@ -20,6 +20,8 @@ local strategy = {
 }
 
 
+---@class TransHover
+---@field execute fun(hover: TransHover, action: string)
 return function(hover, action)
     -- TODO :
     strategy[action](hover)
diff --git a/lua/Trans/frontend/hover/init.lua b/lua/Trans/frontend/hover/init.lua
index 0168700..902b245 100644
--- a/lua/Trans/frontend/hover/init.lua
+++ b/lua/Trans/frontend/hover/init.lua
@@ -1,23 +1,13 @@
 local Trans = require('Trans')
 
----@class hover
+
+---@class TransHover: TransFrontend
+---@field ns integer @namespace for hover window
 ---@field buffer TransBuffer @buffer for hover window
 ---@field window TransWindow @hover window
----@field queue hover[] @hover queue for all hover instances
----@field destroy_funcs table @functions to be executed when hover window is closed
----@field opts table @options for hover window
----@field opts.title string @title for hover window
----@field opts.width number @width for hover window
----@field opts.height number @height for hover window
----@field opts.animation boolean @whether to use animation for hover window
----@field opts.fallback_message string @message to be displayed when hover window is waiting for data
----@field opts.spinner string @spinner to be displayed when hover window is waiting for data
----@field opts.icon table @icons for hover window
----@field opts.icon.notfound string @icon for not found
----@field opts.icon.yes string @icon for yes
----@field opts.icon.no string @icon for no
----@field opts.icon.star string @icon for star
----@field opts.icon.cell string @icon for cell used in waitting animation
+---@field queue TransHover[] @hover queue for all hover instances
+---@field destroy_funcs fun(hover:TransHover)[] @functions to be executed when hover window is closed
+---@field opts TransHoverOpts @options for hover window
 local M = Trans.metatable('frontend.hover', {
     ns    = vim.api.nvim_create_namespace('TransHoverWin'),
     queue = {},
@@ -25,7 +15,7 @@ local M = Trans.metatable('frontend.hover', {
 M.__index = M
 
 ---Create a new hover instance
----@return hover new_instance
+---@return TransHover new_instance
 function M.new()
     local new_instance = {
         buffer = Trans.buffer.new(),
@@ -37,7 +27,7 @@ function M.new()
 end
 
 ---Get the first active instances
----@return hover
+---@return TransHover
 function M.get_active_instance()
     M.clear_dead_instance()
     return M.queue[1]
@@ -66,7 +56,8 @@ function M:destroy()
 end
 
 ---Init hover window
----@param opts table? @window options: width, height
+---@param opts?
+---|{win_opts: WindowOpts,}
 ---@return unknown
 function M:init_window(opts)
     opts           = opts or {}
@@ -104,11 +95,11 @@ function M:wait(tbl, name, timeout)
     local size    = #spinner
     local cell    = self.opts.icon.cell
 
-
     local function update_text(times)
         return spinner[times % size + 1] .. (cell):rep(times)
     end
 
+
     self:init_window({
         win_opts = {
             height = 1,
@@ -130,6 +121,10 @@ function M:wait(tbl, name, timeout)
     buffer[1] = ''
 end
 
+---Display Result in hover window
+---@param _ any
+---@param result TransResult
+---@overload fun(result:TransResult)
 function M:process(_, result)
     -- local node = Trans.util.node
     -- local it, t, f = node.item, node.text, node.format
@@ -158,6 +153,8 @@ function M:is_available()
     return self.buffer:is_valid() and self.window:is_valid()
 end
 
+---@class TransFrontend
+---@field hover TransHover @hover frontend
 return M
 --     local cmd_id
 --     local next
diff --git a/lua/Trans/frontend/hover/load.lua b/lua/Trans/frontend/hover/load.lua
index 9b02611..6e5dad4 100644
--- a/lua/Trans/frontend/hover/load.lua
+++ b/lua/Trans/frontend/hover/load.lua
@@ -1,7 +1,6 @@
 local node = require('Trans').util.node
 local it, t, f = node.item, node.text, node.format
 
-
 local function conjunction(text)
     return {
         it('', 'TransTitleRound'),
@@ -116,6 +115,11 @@ local strategy = {
     end,
 }
 
+
+
+
+---@class TransHover
+---@field load fun(hover: TransHover, result: TransResult, field: string)
 return function(hover, result, field)
     strategy[field](hover, result[field])
 end
diff --git a/lua/Trans/init.lua b/lua/Trans/init.lua
index d3a9980..565f3ae 100644
--- a/lua/Trans/init.lua
+++ b/lua/Trans/init.lua
@@ -5,9 +5,11 @@
 local function metatable(folder_name, origin)
     return setmetatable(origin or {}, {
         __index = function(tbl, key)
-            local result = require(('Trans.%s.%s'):format(folder_name, key))
-            tbl[key] = result
-            return result
+            local status, result = pcall(require, ('Trans.%s.%s'):format(folder_name, key))
+            if status then
+                tbl[key] = result
+                return result
+            end
         end
     })
 end
diff --git a/lua/Trans/util/md5.lua b/lua/Trans/util/md5.lua
index 4b3fdfb..fa03ac5 100644
--- a/lua/Trans/util/md5.lua
+++ b/lua/Trans/util/md5.lua
@@ -1,3 +1,7 @@
+---@class TransUtil
+---@field md5 TransUtilMd5
+
+---@class TransUtilMd5
 local md5 = {}
 -- local md5 = {
 --     _VERSION     = "md5.lua 1.1.0",