chore: Use some of the new annotations.

sindrets · sindrets · commit f32a7224096c · 2022-11-17T23:49:23.000+01:00
Use `@enum` everywhere it applies.
Use `@private`.
diff --git a/lua/diffview/diff.lua b/lua/diffview/diff.lua
@@ -5,17 +5,13 @@
 local oop = require("diffview.oop")
 local M = {}
 
----@class EditToken
----@field NOOP integer
----@field DELETE integer
----@field INSERT integer
----@field REPLACE integer
-local EditToken = oop.enum({
-  "NOOP",
-  "DELETE",
-  "INSERT",
-  "REPLACE",
-})
+---@enum EditToken
+local EditToken = {
+  NOOP    = 1,
+  DELETE  = 2,
+  INSERT  = 3,
+  REPLACE = 4,
+}
 
 ---@class Diff : diffview.Object
 ---@field a any[]
diff --git a/lua/diffview/events.lua b/lua/diffview/events.lua
@@ -6,13 +6,10 @@ local utils = lazy.require("diffview.utils")
 
 local M = {}
 
----@class Event
-
----@class EEvent
----@field FILES_STAGED Event
-local Event = oop.enum({
-  "FILES_STAGED",
-})
+---@enum Event
+local Event = {
+  FILES_STAGED = 1,
+}
 
 ---@alias ListenerType '"normal"'|'"once"'|'"any"'|'"any_once"'
 
diff --git a/lua/diffview/lib.lua b/lua/diffview/lib.lua
@@ -46,7 +46,6 @@ function M.diffview_open(args)
     return
   end
 
-  ---@type DiffView
   local v = DiffView({
     adapter = adapter,
     rev_arg = rev_arg,
@@ -97,7 +96,6 @@ function M.file_history(range, args)
     return
   end
 
-  ---@type FileHistoryView
   local v = FileHistoryView({
     adapter = adapter,
     log_options = log_options,
diff --git a/lua/diffview/path.lua b/lua/diffview/path.lua
@@ -23,10 +23,12 @@ function PathLib:init(o)
   self.cwd = o.cwd and self:convert(o.cwd) or nil
 end
 
+---@private
 function PathLib:_cwd()
   return self.cwd or self:convert(uv.cwd())
 end
 
+---@private
 ---@return ...
 function PathLib:_clean(...)
   local argc = select("#", ...)
diff --git a/lua/diffview/scene/layouts/diff_3.lua b/lua/diffview/scene/layouts/diff_3.lua
@@ -3,16 +3,11 @@ local Window = require("diffview.scene.window").Window
 local Layout = require("diffview.scene.layout").Layout
 local oop = require("diffview.oop")
 
----@type Diff1|LazyModule
-local Diff1 = lazy.access("diffview.scene.layouts.diff_1", "Diff1")
----@type Diff4|LazyModule
-local Diff4 = lazy.access("diffview.scene.layouts.diff_4", "Diff4")
----@type vcs.File|LazyModule
-local File = lazy.access("diffview.vcs.file", "File")
----@type Rev|LazyModule
-local Rev = lazy.access("diffview.vcs.rev", "Rev")
----@type ERevType|LazyModule
-local RevType = lazy.access("diffview.vcs.rev", "RevType")
+local Diff1 = lazy.access("diffview.scene.layouts.diff_1", "Diff1") ---@type Diff1|LazyModule
+local Diff4 = lazy.access("diffview.scene.layouts.diff_4", "Diff4") ---@type Diff4|LazyModule
+local File = lazy.access("diffview.vcs.file", "File") ---@type vcs.File|LazyModule
+local Rev = lazy.access("diffview.vcs.rev", "Rev") ---@type Rev|LazyModule
+local RevType = lazy.access("diffview.vcs.rev", "RevType") ---@type RevType|LazyModule
 
 local M = {}
 
diff --git a/lua/diffview/scene/views/diff/diff_view.lua b/lua/diffview/scene/views/diff/diff_view.lua
@@ -12,11 +12,11 @@ local PerfTimer = lazy.access("diffview.perf", "PerfTimer") ---@type PerfTimer|L
 local RevType = lazy.access("diffview.vcs.rev", "RevType") ---@type RevType|LazyModule
 local StandardView = lazy.access("diffview.scene.views.standard.standard_view", "StandardView") ---@type StandardView|LazyModule
 local async = lazy.require("plenary.async") ---@module "plenary.async"
+local config = lazy.require("diffview.config") ---@module "diffview.config"
 local debounce = lazy.require("diffview.debounce") ---@module "diffview.debounce"
-local vcs = lazy.require("diffview.vcs.utils") ---@module "diffview.vcs.utils"
 local logger = lazy.require("diffview.logger") ---@module "diffview.logger"
 local utils = lazy.require("diffview.utils") ---@module "diffview.utils"
-local config = lazy.require("diffview.config") ---@module "diffview.config"
+local vcs = lazy.require("diffview.vcs.utils") ---@module "diffview.vcs.utils"
 
 local api = vim.api
 local M = {}
@@ -26,6 +26,7 @@ local M = {}
 ---@field selected_file? string Path to the preferred initially selected file.
 
 ---@class DiffView : StandardView
+---@operator call:DiffView
 ---@field adapter VCSAdapter
 ---@field rev_arg string
 ---@field path_args string[]
@@ -167,6 +168,7 @@ function DiffView:close()
   end
 end
 
+---@private
 ---@param file FileEntry
 function DiffView:_set_file(file)
   vim.cmd("redraw")
diff --git a/lua/diffview/scene/views/diff/listeners.lua b/lua/diffview/scene/views/diff/listeners.lua
@@ -1,11 +1,11 @@
 local lazy = require("diffview.lazy")
 
+local Event = lazy.access("diffview.events", "Event") ---@type Event|LazyModule
+local RevType = lazy.access("diffview.vcs.rev", "RevType") ---@type RevType|LazyModule
 local actions = lazy.require("diffview.actions") ---@module "diffview.actions"
-local Event = lazy.access("diffview.events", "Event") ---@type EEvent
-local RevType = lazy.access("diffview.vcs.rev", "RevType") ---@type ERevType
 local async = lazy.require("plenary.async") ---@module "plenary.async"
-local vcs = lazy.require("diffview.vcs.utils") ---@module "diffview.vcs.utils"
 local utils = lazy.require("diffview.utils") ---@module "diffview.utils"
+local vcs = lazy.require("diffview.vcs.utils") ---@module "diffview.vcs.utils"
 
 local api = vim.api
 
diff --git a/lua/diffview/scene/views/file_history/file_history_panel.lua b/lua/diffview/scene/views/file_history/file_history_panel.lua
@@ -380,6 +380,12 @@ function FileHistoryPanel:cur_file()
   return self.cur_item[2]
 end
 
+---@private
+---@param entry_idx integer
+---@param file_idx integer
+---@param offset integer
+---@return LogEntry?
+---@return FileEntry?
 function FileHistoryPanel:_get_entry_by_file_offset(entry_idx, file_idx, offset)
   local cur_entry = self.entries[entry_idx]
 
diff --git a/lua/diffview/scene/views/file_history/file_history_view.lua b/lua/diffview/scene/views/file_history/file_history_view.lua
@@ -5,15 +5,16 @@ local CommitLogPanel = lazy.access("diffview.ui.panels.commit_log_panel", "Commi
 local Event = lazy.access("diffview.events", "Event") ---@type Event|LazyModule
 local FileEntry = lazy.access("diffview.scene.file_entry", "FileEntry") ---@type FileEntry|LazyModule
 local FileHistoryPanel = lazy.access("diffview.scene.views.file_history.file_history_panel", "FileHistoryPanel") ---@type FileHistoryPanel|LazyModule
+local JobStatus = lazy.access("diffview.vcs.utils", "JobStatus") ---@type JobStatus|LazyModule
 local StandardView = lazy.access("diffview.scene.views.standard.standard_view", "StandardView") ---@type StandardView|LazyModule
 local config = lazy.require("diffview.config") ---@module "diffview.config"
 
-local JobStatus = lazy.access("diffview.vcs.utils", "JobStatus") ---@type JobStatus|LazyModule
 local api = vim.api
 
 local M = {}
 
 ---@class FileHistoryView : StandardView
+---@operator call:FileHistoryView
 ---@field adapter VCSAdapter
 ---@field panel FileHistoryPanel
 ---@field commit_log_panel CommitLogPanel
@@ -79,6 +80,7 @@ function FileHistoryView:cur_file()
   return self.panel.cur_item[2]
 end
 
+---@private
 ---@param file FileEntry
 function FileHistoryView:_set_file(file)
   vim.cmd("redraw")
diff --git a/lua/diffview/scene/views/file_history/option_panel.lua b/lua/diffview/scene/views/file_history/option_panel.lua
@@ -154,6 +154,7 @@ function FHOptionPanel:init(parent)
   })
 end
 
+---@private
 function FHOptionPanel:_set_option(name, value)
   self.parent.log_options.single_file[name] = value
   self.parent.log_options.multi_file[name] = value
diff --git a/lua/diffview/scene/window.lua b/lua/diffview/scene/window.lua
@@ -125,6 +125,7 @@ function Window:detach_file()
 end
 
 ---Check if the file buffer is in use in the current view's layout.
+---@private
 ---@return boolean
 function Window:_is_file_in_use()
   local view = lib.get_current_view() --[[@as StandardView? ]]
diff --git a/lua/diffview/vcs/adapter.lua b/lua/diffview/vcs/adapter.lua
@@ -27,7 +27,7 @@ local M = {}
 ---@class vcs.adapter.VCSAdapter.Ctx
 ---@field toplevel string # VCS repository toplevel directory
 ---@field dir string # VCS directory
----@field path_args string[] # Extra path arguments
+---@field path_args string[] # Resolved path arguments
 
 ---@class VCSAdapter: diffview.Object
 ---@field bootstrap vcs.adapter.VCSAdapter.Bootstrap
diff --git a/lua/diffview/vcs/adapters/git/commit.lua b/lua/diffview/vcs/adapters/git/commit.lua
@@ -2,7 +2,7 @@ local lazy = require("diffview.lazy")
 local oop = require('diffview.oop')
 
 local Commit = lazy.access("diffview.vcs.commit", "Commit") ---@type Commit|LazyModule
-local RevType = lazy.access("diffview.vcs.rev", "RevType") ---@type ERevType|LazyModule
+local RevType = lazy.access("diffview.vcs.rev", "RevType") ---@type RevType|LazyModule
 local utils = lazy.require("diffview.utils") ---@module "diffview.utils"
 
 local M = {}
diff --git a/lua/diffview/vcs/adapters/git/init.lua b/lua/diffview/vcs/adapters/git/init.lua
@@ -90,14 +90,10 @@ end
 ---@param path string
 ---@return string?
 local function get_toplevel(path)
-  local out, code = utils.system_list(
-    vim.tbl_flatten({
-      config.get_config().git_cmd,
-      { "rev-parse", "--path-format=absolute", "--show-toplevel" },
-    }),
-    { cwd = path }
-  )
-
+  local out, code = utils.system_list(vim.tbl_flatten({
+    config.get_config().git_cmd,
+    { "rev-parse", "--path-format=absolute", "--show-toplevel" },
+  }), path)
   if code ~= 0 then
     return nil
   end
@@ -136,6 +132,7 @@ end
 ---@param toplevel string
 ---@param path_args string[]
 ---@param cpath string?
+---@return GitAdapter
 function M.create(toplevel, path_args, cpath)
   return GitAdapter({
     toplevel = toplevel,
diff --git a/lua/diffview/vcs/adapters/git/rev.lua b/lua/diffview/vcs/adapters/git/rev.lua
@@ -58,7 +58,7 @@ function GitRev.from_name(name, adapter)
   return GitRev(RevType.COMMIT, out[1]:gsub("^%^", ""))
 end
 
----@param adapter VCSAdapter
+---@param adapter GitAdapter
 ---@return Rev?
 function GitRev.earliest_commit(adapter)
   local out, code = adapter:exec_sync({
@@ -72,12 +72,10 @@ function GitRev.earliest_commit(adapter)
   return GitRev(RevType.COMMIT, ({ out[1]:gsub("^%^", "") })[1])
 end
 
-function GitRev:object_name()
-  if self.type == RevType.COMMIT then
-    return self.commit
-  elseif self.type == RevType.STAGE then
-    return ":" ..  self.stage
-  end
+---Create a new commit rev with the special empty tree SHA.
+---@return Rev
+function GitRev.new_null_tree()
+  return GitRev(RevType.COMMIT, GitRev.NULL_TREE_SHA)
 end
 
 ---Determine if this rev is currently the head.
@@ -97,10 +95,12 @@ function Rev:is_head(adapter)
   return self.commit == vim.trim(out[1]):gsub("^%^", "")
 end
 
----Create a new commit rev with the special empty tree SHA.
----@return Rev
-function GitRev.new_null_tree()
-  return GitRev(RevType.COMMIT, GitRev.NULL_TREE_SHA)
+function GitRev:object_name()
+  if self.type == RevType.COMMIT then
+    return self.commit
+  elseif self.type == RevType.STAGE then
+    return ":" ..  self.stage
+  end
 end
 
 M.GitRev = GitRev
diff --git a/lua/diffview/vcs/commit.lua b/lua/diffview/vcs/commit.lua
@@ -1,7 +1,7 @@
 local lazy = require("diffview.lazy")
 local oop = require("diffview.oop")
 
-local RevType = lazy.access("diffview.vcs.rev", "RevType") ---@type ERevType|LazyModule
+local RevType = lazy.access("diffview.vcs.rev", "RevType") ---@type RevType|LazyModule
 local utils = lazy.require("diffview.utils") ---@module "diffview.utils"
 
 local M = {}
diff --git a/lua/diffview/vcs/file.lua b/lua/diffview/vcs/file.lua
@@ -1,8 +1,8 @@
 local lazy = require("diffview.lazy")
 local oop = require("diffview.oop")
 
-local Rev = lazy.access("diffview.vcs.rev", "Rev") ---@type Rev|LazyModule
-local RevType = lazy.access("diffview.vcs.rev", "RevType") ---@type ERevType|LazyModule
+local GitRev = lazy.access("diffview.vcs.adapters.git.rev", "GitRev") ---@type GitRev|LazyModule
+local RevType = lazy.access("diffview.vcs.rev", "RevType") ---@type RevType|LazyModule
 local async = lazy.require("plenary.async") ---@module "plenary.async"
 local config = lazy.require("diffview.config") ---@module "diffview.config"
 local utils = lazy.require("diffview.utils") ---@module "diffview.utils"
@@ -391,7 +391,7 @@ File.NULL_FILE = File({
   status = "X",
   binary = false,
   nulled = true,
-  rev = Rev.new_null_tree(),
+  rev = GitRev.new_null_tree(),
 })
 
 M.File = File
diff --git a/lua/diffview/vcs/rev.lua b/lua/diffview/vcs/rev.lua
@@ -2,19 +2,13 @@ local oop = require("diffview.oop")
 
 local M = {}
 
----@class RevType : EnumValue
-
----@class ERevType
----@field LOCAL RevType
----@field COMMIT RevType
----@field STAGE RevType
----@field CUSTOM RevType
-local RevType = oop.enum({
-  "LOCAL",
-  "COMMIT",
-  "STAGE",
-  "CUSTOM",
-})
+---@enum RevType
+local RevType = {
+  LOCAL   = 1,
+  COMMIT  = 2,
+  STAGE   = 3,
+  CUSTOM  = 4,
+}
 
 ---@alias RevRange { first: Rev, last: Rev }
 
@@ -70,19 +64,36 @@ function Rev:__tostring()
   end
 end
 
+---@diagnostic disable: unused-local, missing-return
+
 ---@param name string
 ---@param adapter? VCSAdapter
 ---@return Rev?
 function Rev.from_name(name, adapter)
   oop.abstract_stub()
 end
 
----@param git_toplevel string
+---@param adapter VCSAdapter
 ---@return Rev?
-function Rev.earliest_commit(git_toplevel)
+function Rev.earliest_commit(adapter)
+  oop.abstract_stub()
+end
+
+---Create a new commit rev with the special empty tree SHA.
+---@return Rev
+function Rev.new_null_tree()
+  oop.abstract_stub()
+end
+
+---Determine if this rev is currently the head.
+---@param adapter VCSAdapter
+---@return boolean?
+function Rev:is_head(adapter)
   oop.abstract_stub()
 end
 
+---@diagnostic enable: unused-local, missing-return
+
 function Rev:object_name()
   oop.abstract_stub()
 end
@@ -97,19 +108,6 @@ function Rev:abbrev(length)
   return nil
 end
 
----Determine if this rev is currently the head.
----@param adapter VCSAdapter
----@return boolean?
-function Rev:is_head(adapter)
-  oop.abstract_stub()
-end
-
----Create a new commit rev with the special empty tree SHA.
----@return Rev
-function Rev.new_null_tree()
-  return nil
-end
-
 M.RevType = RevType
 M.Rev = Rev
 
diff --git a/lua/diffview/vcs/utils.lua b/lua/diffview/vcs/utils.lua
