From 3f206db69ac288723a1f4a7ed87b81f830998317 Mon Sep 17 00:00:00 2001
From: jgmdev <jgmdev@gmail.com>
Date: Tue, 7 Jun 2022 20:09:48 -0400
Subject: [PATCH] initial documentation for better code completion

---
 changelog.md              |  10 ++-
 data/core/commandview.lua |  20 ++++-
 data/core/contextmenu.lua |   1 +
 data/core/doc/init.lua    |   2 +-
 data/core/docview.lua     |   3 +-
 data/core/emptyview.lua   |   2 +
 data/core/init.lua        |   5 ++
 data/core/nagview.lua     |   2 +
 data/core/node.lua        |   1 +
 data/core/object.lua      |  23 ++++--
 data/core/rootview.lua    |  39 +++++++++-
 data/core/statusview.lua  | 156 +++++++++++++++++++-------------------
 data/core/titleview.lua   |   2 +
 data/core/view.lua        |  92 ++++++++++++++++++++--
 data/plugins/treeview.lua |   4 +-
 15 files changed, 262 insertions(+), 100 deletions(-)

diff --git a/changelog.md b/changelog.md
index 8241ceeb..bf61310d 100644
--- a/changelog.md
+++ b/changelog.md
@@ -178,7 +178,9 @@
 
 * [CommandView:enter](https://github.com/lite-xl/lite-xl/pull/1004) now accepts
   a single options table as a parameter, meaning that the old way of calling
-  this function will now show a deprecation message.
+  this function will now show a deprecation message. Also `CommandView:set_text`
+  and `CommandView:set_hidden_suggestions` has been
+  [deprecated](https://github.com/lite-xl/lite-xl/pull/1014).
 
   **Example:**
   ```lua
@@ -187,6 +189,9 @@
     suggest = function() return end,
     cancel = function() end,
     validate = function() return true end,
+    text = "",
+    select_text = false,
+    show_suggestions = true,
     typeahead = true,
     wrap = true
   })
@@ -283,6 +288,9 @@
 * TreeView improvements for
   [multi-project](https://github.com/lite-xl/lite-xl/pull/1010).
 
+* Open LogView on user/project
+  [module reload error](https://github.com/lite-xl/lite-xl/pull/1022).
+
 * Many, many, many more changes that are too numerous to list.
 
 ## [2.0.5] - 2022-01-29
diff --git a/data/core/commandview.lua b/data/core/commandview.lua
index 8017fcfc..545455e6 100644
--- a/data/core/commandview.lua
+++ b/data/core/commandview.lua
@@ -6,13 +6,16 @@ local DocView = require "core.docview"
 local View = require "core.view"
 
 
+---@class core.commandview.input : core.doc
+---@field super core.doc
 local SingleLineDoc = Doc:extend()
 
 function SingleLineDoc:insert(line, col, text)
   SingleLineDoc.super.insert(self, line, col, text:gsub("\n", ""))
 end
 
-
+---@class core.commandview : core.docview
+---@field super core.docview
 local CommandView = DocView:extend()
 
 CommandView.context = "application"
@@ -21,6 +24,16 @@ local max_suggestions = 10
 
 local noop = function() end
 
+---@class core.commandview.state
+---@field submit function
+---@field suggest function
+---@field cancel function
+---@field validate function
+---@field text string
+---@field select_text boolean
+---@field show_suggestions boolean
+---@field typeahead boolean
+---@field wrap boolean
 local default_state = {
   submit = noop,
   suggest = noop,
@@ -51,6 +64,7 @@ function CommandView:new()
 end
 
 
+---@deprecated
 function CommandView:set_hidden_suggestions()
   core.warn("Using deprecated function CommandView:set_hidden_suggestions")
   self.state.show_suggestions = false
@@ -147,7 +161,9 @@ function CommandView:submit()
   end
 end
 
-
+---@param label string
+---@varargs any
+---@overload fun(label:string, options: core.commandview.state)
 function CommandView:enter(label, ...)
   if self.state ~= default_state then
     return
diff --git a/data/core/contextmenu.lua b/data/core/contextmenu.lua
index 94ef61f8..040fe6c3 100644
--- a/data/core/contextmenu.lua
+++ b/data/core/contextmenu.lua
@@ -11,6 +11,7 @@ local border_width = 1
 local divider_width = 1
 local DIVIDER = {}
 
+---@class core.contextmenu : core.object
 local ContextMenu = Object:extend()
 
 ContextMenu.DIVIDER = DIVIDER
diff --git a/data/core/doc/init.lua b/data/core/doc/init.lua
index a2546246..fc2226cb 100644
--- a/data/core/doc/init.lua
+++ b/data/core/doc/init.lua
@@ -5,7 +5,7 @@ local syntax = require "core.syntax"
 local config = require "core.config"
 local common = require "core.common"
 
-
+---@class core.doc : core.object
 local Doc = Object:extend()
 
 
diff --git a/data/core/docview.lua b/data/core/docview.lua
index bf76db38..f4270e9f 100644
--- a/data/core/docview.lua
+++ b/data/core/docview.lua
@@ -6,7 +6,8 @@ local keymap = require "core.keymap"
 local translate = require "core.doc.translate"
 local View = require "core.view"
 
-
+---@class core.docview : core.view
+---@field super core.view
 local DocView = View:extend()
 
 DocView.context = "session"
diff --git a/data/core/emptyview.lua b/data/core/emptyview.lua
index 36ba8fb7..0d0a929e 100644
--- a/data/core/emptyview.lua
+++ b/data/core/emptyview.lua
@@ -2,6 +2,8 @@ local style = require "core.style"
 local keymap = require "core.keymap"
 local View = require "core.view"
 
+---@class core.emptyview : core.view
+---@field super core.view
 local EmptyView = View:extend()
 
 local function draw_text(x, y, color)
diff --git a/data/core/init.lua b/data/core/init.lua
index 2c487dff..f8459e3f 100644
--- a/data/core/init.lua
+++ b/data/core/init.lua
@@ -694,10 +694,15 @@ function core.init()
   core.quit_request = false
 
   -- We load core views before plugins that may need them.
+  ---@type core.rootview
   core.root_view = RootView()
+  ---@type core.commandview
   core.command_view = CommandView()
+  ---@type core.statusview
   core.status_view = StatusView()
+  ---@type core.nagview
   core.nag_view = NagView()
+  ---@type core.titleview
   core.title_view = TitleView()
 
   -- Some plugins (eg: console) require the nodes to be initialized to defaults
diff --git a/data/core/nagview.lua b/data/core/nagview.lua
index c34d2a64..9c373f58 100644
--- a/data/core/nagview.lua
+++ b/data/core/nagview.lua
@@ -11,6 +11,8 @@ local UNDERLINE_MARGIN = common.round(1 * SCALE)
 
 local noop = function() end
 
+---@class core.nagview : core.view
+---@field super core.view
 local NagView = View:extend()
 
 function NagView:new()
diff --git a/data/core/node.lua b/data/core/node.lua
index fee62ba6..087610a6 100644
--- a/data/core/node.lua
+++ b/data/core/node.lua
@@ -6,6 +6,7 @@ local Object = require "core.object"
 local EmptyView = require "core.emptyview"
 local View = require "core.view"
 
+---@class core.node : core.object
 local Node = Object:extend()
 
 function Node:new(type)
diff --git a/data/core/object.lua b/data/core/object.lua
index 6a6ea490..afd13cdf 100644
--- a/data/core/object.lua
+++ b/data/core/object.lua
@@ -1,11 +1,12 @@
+---@class core.object
+---@field super core.object
 local Object = {}
 Object.__index = Object
 
+---Can be overrided by child objects to implement a constructor.
+function Object:new() end
 
-function Object:new()
-end
-
-
+---@return core.object
 function Object:extend()
   local cls = {}
   for k, v in pairs(self) do
@@ -19,12 +20,16 @@ function Object:extend()
   return cls
 end
 
-
+---Check if the object is strictly of the given type.
+---@param T any
+---@return boolean
 function Object:is(T)
   return getmetatable(self) == T
 end
 
-
+---Check if the object inherits from the given type.
+---@param T any
+---@return boolean
 function Object:extends(T)
   local mt = getmetatable(self)
   while mt do
@@ -36,12 +41,14 @@ function Object:extends(T)
   return false
 end
 
-
+---Metamethod to get a string representation of an object.
+---@return string
 function Object:__tostring()
   return "Object"
 end
 
-
+---Methamethod to allow using the object call as a constructor.
+---@return core.object
 function Object:__call(...)
   local obj = setmetatable({}, self)
   obj:new(...)
diff --git a/data/core/rootview.lua b/data/core/rootview.lua
index 8e32c68c..c4eb656f 100644
--- a/data/core/rootview.lua
+++ b/data/core/rootview.lua
@@ -5,7 +5,10 @@ local Node = require "core.node"
 local View = require "core.view"
 local DocView = require "core.docview"
 
-
+---@class core.rootview : core.view
+---@field super core.view
+---@field root_node core.node
+---@field mouse core.view.position
 local RootView = View:extend()
 
 function RootView:new()
@@ -29,6 +32,7 @@ function RootView:defer_draw(fn, ...)
 end
 
 
+---@return core.node
 function RootView:get_active_node()
   local node = self.root_node:get_node_for_view(core.active_view)
   if not node then node = self:get_primary_node() end
@@ -36,6 +40,7 @@ function RootView:get_active_node()
 end
 
 
+---@return core.node
 local function get_primary_node(node)
   if node.is_primary_node then
     return node
@@ -46,6 +51,7 @@ local function get_primary_node(node)
 end
 
 
+---@return core.node
 function RootView:get_active_node_default()
   local node = self.root_node:get_node_for_view(core.active_view)
   if not node then node = self:get_primary_node() end
@@ -59,11 +65,14 @@ function RootView:get_active_node_default()
 end
 
 
+---@return core.node
 function RootView:get_primary_node()
   return get_primary_node(self.root_node)
 end
 
 
+---@param node core.node
+---@return core.node
 local function select_next_primary_node(node)
   if node.is_primary_node then return end
   if node.type ~= "leaf" then
@@ -77,11 +86,14 @@ local function select_next_primary_node(node)
 end
 
 
+---@return core.node
 function RootView:select_next_primary_node()
   return select_next_primary_node(self.root_node)
 end
 
 
+---@param doc core.doc
+---@return core.docview
 function RootView:open_doc(doc)
   local node = self:get_active_node_default()
   for i, view in ipairs(node.views) do
@@ -98,17 +110,27 @@ function RootView:open_doc(doc)
 end
 
 
+---@param keep_active boolean
 function RootView:close_all_docviews(keep_active)
   self.root_node:close_all_docviews(keep_active)
 end
 
 
--- Function to intercept mouse pressed events on the active view.
--- Do nothing by default.
+---Function to intercept mouse pressed events on the active view.
+---Do nothing by default.
+---@param button core.view.mousebutton
+---@param x number
+---@param y number
+---@param clicks integer
 function RootView.on_view_mouse_pressed(button, x, y, clicks)
 end
 
 
+---@param button core.view.mousebutton
+---@param x number
+---@param y number
+---@param clicks integer
+---@return boolean
 function RootView:on_mouse_pressed(button, x, y, clicks)
   local div = self.root_node:get_divider_overlapping_point(x, y)
   local node = self.root_node:get_child_overlapping_point(x, y)
@@ -162,6 +184,9 @@ function RootView:set_show_overlay(overlay, status)
 end
 
 
+---@param button core.view.mousebutton
+---@param x number
+---@param y number
 function RootView:on_mouse_released(button, x, y, ...)
   if self.dragged_divider then
     self.dragged_divider = nil
@@ -220,6 +245,10 @@ local function resize_child_node(node, axis, value, delta)
 end
 
 
+---@param x number
+---@param y number
+---@param dx number
+---@param dy number
 function RootView:on_mouse_moved(x, y, dx, dy)
   if core.active_view == core.nag_view then
     core.request_cursor("arrow")
@@ -284,6 +313,10 @@ function RootView:on_mouse_left()
 end
 
 
+---@param filename string
+---@param x number
+---@param y number
+---@return boolean
 function RootView:on_file_dropped(filename, x, y)
   local node = self.root_node:get_child_overlapping_point(x, y)
   return node and node.active_view:on_file_dropped(filename, x, y)
diff --git a/data/core/statusview.lua b/data/core/statusview.lua
index 542522c7..497e5e2e 100644
--- a/data/core/statusview.lua
+++ b/data/core/statusview.lua
@@ -10,17 +10,18 @@ local View = require "core.view"
 local Object = require "core.object"
 
 
----@alias StatusView.styledtext table<integer, renderer.font|renderer.color|string>
+---@alias core.statusview.styledtext table<integer, renderer.font|renderer.color|string>
 
 ---A status bar implementation for lite, check core.status_view.
----@class StatusView : View
----@field private items StatusView.Item[]
----@field private active_items StatusView.Item[]
----@field private hovered_item StatusView.Item
+---@class core.statusview : core.view
+---@field public super core.view
+---@field private items core.statusview.item[]
+---@field private active_items core.statusview.item[]
+---@field private hovered_item core.statusview.item
 ---@field private message_timeout number
----@field private message StatusView.styledtext
+---@field private message core.statusview.styledtext
 ---@field private tooltip_mode boolean
----@field private tooltip StatusView.styledtext
+---@field private tooltip core.statusview.styledtext
 ---@field private left_width number
 ---@field private right_width number
 ---@field private r_left_width number
@@ -40,52 +41,52 @@ StatusView.separator  = "      "
 ---@type string
 StatusView.separator2 = "   |   "
 
----@alias StatusView.Item.separator
----|>'StatusView.separator' # Space separator
----| 'StatusView.separator2' # Pipe separator
+---@alias core.statusview.item.separator
+---|>'core.statusview.separator' # Space separator
+---| 'core.statusview.separator2' # Pipe separator
 
----@alias StatusView.Item.predicate fun():boolean
----@alias StatusView.Item.onclick fun(button: string, x: number, y: number)
----@alias StatusView.Item.getitem fun():StatusView.styledtext,StatusView.styledtext
----@alias StatusView.Item.ondraw fun(x, y, h, hovered: boolean, calc_only: boolean):number
+---@alias core.statusview.item.predicate fun():boolean
+---@alias core.statusview.item.onclick fun(button: string, x: number, y: number)
+---@alias core.statusview.item.getitem fun():core.statusview.styledtext,core.statusview.styledtext
+---@alias core.statusview.item.ondraw fun(x, y, h, hovered: boolean, calc_only?: boolean):number
 
----@class StatusView.Item : Object
+---@class core.statusview.item : core.object
 ---@field name string
----@field predicate StatusView.Item.predicate
----@field alignment StatusView.Item.alignment
+---@field predicate core.statusview.item.predicate
+---@field alignment core.statusview.item.alignment
 ---@field tooltip string | nil
 ---@field command string | nil @Command to perform when the item is clicked.
----@field on_click StatusView.Item.onclick | nil @Function called when item is clicked and no command is set.
----@field on_draw StatusView.Item.ondraw | nil @Custom drawing that when passed calc true should return the needed width for drawing and when false should draw.
+---@field on_click core.statusview.item.onclick | nil @Function called when item is clicked and no command is set.
+---@field on_draw core.statusview.item.ondraw | nil @Custom drawing that when passed calc true should return the needed width for drawing and when false should draw.
 ---@field background_color renderer.color | nil
 ---@field background_color_hover renderer.color | nil
 ---@field visible boolean
----@field separator StatusView.Item.separator
+---@field separator core.statusview.item.separator
 ---@field private active boolean
 ---@field private x number
 ---@field private w number
----@field private cached_item StatusView.styledtext
-StatusView.Item = Object:extend()
+---@field private cached_item core.statusview.styledtext
+local StatusViewItem = Object:extend()
 
 ---Flag to tell the item should me aligned on left side of status bar.
 ---@type number
-StatusView.Item.LEFT = 1
+StatusViewItem.LEFT = 1
 
 ---Flag to tell the item should me aligned on right side of status bar.
 ---@type number
-StatusView.Item.RIGHT = 2
+StatusViewItem.RIGHT = 2
 
----@alias StatusView.Item.alignment
----|>'StatusView.Item.LEFT'
----| 'StatusView.Item.RIGHT'
+---@alias core.statusview.item.alignment
+---|>'core.statusview.item.LEFT'
+---| 'core.statusview.item.RIGHT'
 
 ---Constructor
----@param predicate string | table | StatusView.Item.predicate
+---@param predicate string | table | core.statusview.item.predicate
 ---@param name string
----@param alignment StatusView.Item.alignment
----@param command string | StatusView.Item.onclick
+---@param alignment core.statusview.item.alignment
+---@param command string | core.statusview.item.onclick
 ---@param tooltip? string | nil
-function StatusView.Item:new(predicate, name, alignment, command, tooltip)
+function StatusViewItem:new(predicate, name, alignment, command, tooltip)
   self:set_predicate(predicate)
   self.name = name
   self.alignment = alignment or StatusView.Item.LEFT
@@ -104,25 +105,28 @@ end
 
 ---Called by the status bar each time that the item needs to be rendered,
 ---if on_draw() is set this function is obviated.
----@return StatusView.styledtext
-function StatusView.Item:get_item() return {} end
+---@return core.statusview.styledtext
+function StatusViewItem:get_item() return {} end
 
 ---Do not show the item on the status bar.
-function StatusView.Item:hide() self.visible = false end
+function StatusViewItem:hide() self.visible = false end
 
 ---Show the item on the status bar.
-function StatusView.Item:show() self.visible = true end
+function StatusViewItem:show() self.visible = true end
 
 ---A condition to evaluate if the item should be displayed. If a string
 ---is given it is treated as a require import that should return a valid object
 ---which is checked against the current active view, the sames applies if a
 ---table is given. A function that returns a boolean can be used instead to
 ---perform a custom evaluation, setting to nil means always evaluates to true.
----@param predicate string | table | StatusView.Item.predicate
-function StatusView.Item:set_predicate(predicate)
+---@param predicate string | table | core.statusview.item.predicate
+function StatusViewItem:set_predicate(predicate)
   self.predicate = command.generate_predicate(predicate)
 end
 
+---@type core.statusview.item
+StatusView.Item = StatusViewItem
+
 
 ---Predicated used on the default docview widgets.
 ---@return boolean
@@ -267,9 +271,9 @@ end
 
 
 ---Set a position to the best match according to total available items.
----@param self StatusView
+---@param self core.statusview
 ---@param position integer
----@param alignment StatusView.Item.alignment
+---@param alignment core.statusview.item.alignment
 ---@return integer position
 local function normalize_position(self, position, alignment)
   local offset = 0
@@ -299,18 +303,18 @@ end
 
 
 ---Adds an item to be rendered in the status bar.
----@param predicate string | table | StatusView.Item.predicate :
+---@param predicate string | table | core.statusview.item.predicate :
 ---A condition to evaluate if the item should be displayed. If a string
 ---is given it is treated as a require import that should return a valid object
 ---which is checked against the current active view, the sames applies if a
 ---table is given. A function that returns a boolean can be used instead to
 ---perform a custom evaluation, setting to nil means always evaluates to true.
 ---@param name string A unique name to identify the item on the status bar.
----@param alignment StatusView.Item.alignment
----@param getitem StatusView.Item.getitem :
----A function that should return a StatusView.styledtext element,
+---@param alignment core.statusview.item.alignment
+---@param getitem core.statusview.item.getitem :
+---A function that should return a core.statusview.styledtext element,
 ---returning empty table is allowed.
----@param command? string | StatusView.Item.onclick :
+---@param command? string | core.statusview.item.onclick :
 ---The name of a valid registered command or a callback function to execute
 ---when the item is clicked.
 ---@param pos? integer :
@@ -318,10 +322,10 @@ end
 ---a value of -1 inserts the item at the end which is the default. A value
 ---of 1 will insert the item at the beggining.
 ---@param tooltip? string Displayed when mouse hovers the item
----@return StatusView.Item
+---@return core.statusview.item
 function StatusView:add_item(predicate, name, alignment, getitem, command, pos, tooltip)
   assert(self:get_item(name) == nil, "status item already exists: " .. name)
-  ---@type StatusView.Item
+  ---@type core.statusview.item
   local item = StatusView.Item(predicate, name, alignment, command, tooltip)
   item.get_item = getitem
   pos = type(pos) == "nil" and -1 or tonumber(pos)
@@ -332,7 +336,7 @@ end
 
 ---Get an item object associated to a name or nil if not found.
 ---@param name string
----@return StatusView.Item | nil
+---@return core.statusview.item | nil
 function StatusView:get_item(name)
   for _, item in ipairs(self.items) do
     if item.name == name then return item end
@@ -342,8 +346,8 @@ end
 
 
 ---Get a list of items.
----@param alignment? StatusView.Item.alignment
----@return StatusView.Item[]
+---@param alignment? core.statusview.item.alignment
+---@return core.statusview.item[]
 function StatusView:get_items_list(alignment)
   if alignment then
     local items = {}
@@ -361,7 +365,7 @@ end
 ---Move an item to a different position.
 ---@param name string
 ---@param position integer Can be negative value to position in reverse order
----@param alignment? StatusView.Item.alignment
+---@param alignment? core.statusview.item.alignment
 ---@return boolean moved
 function StatusView:move_item(name, position, alignment)
   assert(name, "no name provided")
@@ -387,7 +391,7 @@ end
 
 ---Remove an item from the status view.
 ---@param name string
----@return StatusView.Item removed_item
+---@return core.statusview.item removed_item
 function StatusView:remove_item(name)
   local item = nil
   for pos, it in ipairs(self.items) do
@@ -493,8 +497,8 @@ end
 
 
 ---Activates tooltip mode displaying only the given
----text until StatusView:remove_tooltip() is called.
----@param text string | StatusView.styledtext
+---text until core.statusview:remove_tooltip() is called.
+---@param text string | core.statusview.styledtext
 function StatusView:show_tooltip(text)
   self.tooltip = type(text) == "table" and text or { text }
   self.tooltip_mode = true
@@ -508,8 +512,8 @@ end
 
 
 ---Helper function to draw the styled text.
----@param self StatusView
----@param items StatusView.styledtext
+---@param self core.statusview
+---@param items core.statusview.styledtext
 ---@param x number
 ---@param y number
 ---@param draw_fn fun(font,color,text,align, x,y,w,h):number
@@ -542,8 +546,8 @@ end
 
 
 ---Draws a table of styled text on the status bar starting on the left or right.
----@param items StatusView.styledtext
----@param right_align boolean
+---@param items core.statusview.styledtext
+---@param right_align? boolean
 ---@param xoffset? number
 ---@param yoffset? number
 function StatusView:draw_items(items, right_align, xoffset, yoffset)
@@ -562,7 +566,7 @@ end
 
 
 ---Draw the tooltip of a given status bar item.
----@param item StatusView.Item
+---@param item core.statusview.item
 function StatusView:draw_item_tooltip(item)
   core.root_view:defer_draw(function()
     local text = item.tooltip
@@ -613,10 +617,10 @@ end
 
 
 ---Helper function to copy a styled text table into another.
----@param t1 StatusView.styledtext
----@param t2 StatusView.styledtext
+---@param t1 core.statusview.styledtext
+---@param t2 core.statusview.styledtext
 local function table_add(t1, t2)
-  for i, value in ipairs(t2) do
+  for _, value in ipairs(t2) do
     table.insert(t1, value)
   end
 end
@@ -624,8 +628,8 @@ end
 
 ---Helper function to merge deprecated items to a temp items table.
 ---@param destination table
----@param items StatusView.styledtext
----@param alignment StatusView.Item.alignment
+---@param items core.statusview.styledtext
+---@param alignment core.statusview.item.alignment
 local function merge_deprecated_items(destination, items, alignment)
   local start = true
   local items_start, items_end = {}, {}
@@ -663,13 +667,13 @@ end
 
 
 ---Append a space item into the given items list.
----@param self StatusView
----@param destination StatusView.Item[]
+---@param self core.statusview
+---@param destination core.statusview.item[]
 ---@param separator string
----@param alignment StatusView.Item.alignment
----@return StatusView.Item
+---@param alignment core.statusview.item.alignment
+---@return core.statusview.item
 local function add_spacing(self, destination, separator, alignment, x)
-  ---@type StatusView.Item
+  ---@type core.statusview.item
   local space = StatusView.Item(nil, "space", alignment)
   space.cached_item = separator == self.separator and {
     style.text, separator
@@ -686,8 +690,8 @@ end
 
 
 ---Remove starting and ending separators.
----@param self StatusView
----@param styled_text StatusView.styledtext
+---@param self core.statusview
+---@param styled_text core.statusview.styledtext
 local function remove_spacing(self, styled_text)
   if
     not Object.is(styled_text[1], renderer.font)
@@ -725,8 +729,6 @@ end
 ---of the status bar checking their predicates and performing positioning
 ---calculations for proper functioning of tooltips and clicks.
 function StatusView:update_active_items()
-  local left, right = {}, {}
-
   local x = self:get_content_offset()
 
   local rx = x + self.size.x
@@ -735,7 +737,7 @@ function StatusView:update_active_items()
 
   self.active_items = {}
 
-  ---@type StatusView.Item[]
+  ---@type core.statusview.item[]
   local combined_items = {}
   table_add(combined_items, self.items)
 
@@ -749,7 +751,7 @@ function StatusView:update_active_items()
   -- calculate left and right width
   for _, item in ipairs(combined_items) do
     item.cached_item = {}
-    if item.visible and item.predicate(self) then
+    if item.visible and item:predicate() then
       local styled_text = type(item.get_item) == "function"
         and item.get_item(self) or item.get_item
 
@@ -890,7 +892,7 @@ function StatusView:get_hovered_panel(x, y)
 end
 
 
----@param item StatusView.Item
+---@param item core.statusview.item
 ---@return number x
 ---@return number w
 function StatusView:get_item_visible_area(item)
@@ -1056,8 +1058,8 @@ end
 
 
 ---Retrieve the hover status and proper background color if any.
----@param self StatusView
----@param item StatusView.Item
+---@param self core.statusview
+---@param item core.statusview.item
 ---@return boolean is_hovered
 ---@return renderer.color | nil color
 local function get_item_bg_color(self, item)
diff --git a/data/core/titleview.lua b/data/core/titleview.lua
index 9090861c..f9d7a961 100644
--- a/data/core/titleview.lua
+++ b/data/core/titleview.lua
@@ -17,6 +17,8 @@ local title_commands = {
   {symbol = "X", action = function() core.quit() end},
 }
 
+---@class core.titleview : core.view
+---@field super core.view
 local TitleView = View:extend()
 
 local function title_view_height()
diff --git a/data/core/view.lua b/data/core/view.lua
index 1f8a9208..04d01230 100644
--- a/data/core/view.lua
+++ b/data/core/view.lua
@@ -4,7 +4,51 @@ local style = require "core.style"
 local common = require "core.common"
 local Object = require "core.object"
 
+---@class core.view.position
+---@field x number
+---@field y number
 
+---@class core.view.scroll
+---@field x number
+---@field y number
+---@field to core.view.position
+
+---@class core.view.thumbtrack
+---@field thumb number
+---@field track number
+
+---@class core.view.thumbtrackwidth
+---@field thumb number
+---@field track number
+---@field to core.view.thumbtrack
+
+---@class core.view.scrollbar
+---@field x core.view.thumbtrack
+---@field y core.view.thumbtrack
+---@field w core.view.thumbtrackwidth
+---@field h core.view.thumbtrack
+
+---@class core.view.increment
+---@field value number
+---@field to number
+
+---@alias core.view.cursor "'arrow'" | "'ibeam'" | "'sizeh'" | "'sizev'" | "'hand'"
+
+---@alias core.view.mousebutton "'left'" | "'right'"
+
+---@alias core.view.context "'application'" | "'session'"
+
+---Base view.
+---@class core.view : core.object
+---@field context core.view.context
+---@field super core.object
+---@field position core.view.position
+---@field size core.view.position
+---@field scroll core.view.scroll
+---@field cursor core.view.cursor
+---@field scrollable boolean
+---@field scrollbar core.view.scrollbar
+---@field scrollbar_alpha core.view.increment
 local View = Object:extend()
 
 -- context can be "application" or "session". The instance of objects
@@ -19,11 +63,11 @@ function View:new()
   self.cursor = "arrow"
   self.scrollable = false
   self.scrollbar = {
-                     x = { thumb = 0, track = 0 },
-                     y = { thumb = 0, track = 0 },
-                     w = { thumb = 0, track = 0, to = { thumb = 0, track = 0 } },
-                     h = { thumb = 0, track = 0 },
-                   }
+    x = { thumb = 0, track = 0 },
+    y = { thumb = 0, track = 0 },
+    w = { thumb = 0, track = 0, to = { thumb = 0, track = 0 } },
+    h = { thumb = 0, track = 0 },
+  }
   self.scrollbar_alpha = { value = 0, to = 0 }
 end
 
@@ -54,16 +98,22 @@ function View:try_close(do_close)
 end
 
 
+---@return string
 function View:get_name()
   return "---"
 end
 
 
+---@return number
 function View:get_scrollable_size()
   return math.huge
 end
 
 
+---@return number x
+---@return number y
+---@return number width
+---@return number height
 function View:get_scrollbar_track_rect()
   local sz = self:get_scrollable_size()
   if sz <= self.size.y or sz == math.huge then
@@ -81,6 +131,10 @@ function View:get_scrollbar_track_rect()
 end
 
 
+---@return number x
+---@return number y
+---@return number width
+---@return number height
 function View:get_scrollbar_rect()
   local sz = self:get_scrollable_size()
   if sz <= self.size.y or sz == math.huge then
@@ -99,17 +153,28 @@ function View:get_scrollbar_rect()
 end
 
 
+---@param x number
+---@param y number
+---@return boolean
 function View:scrollbar_overlaps_point(x, y)
   local sx, sy, sw, sh = self:get_scrollbar_rect()
   return x >= sx - style.scrollbar_size * 3 and x < sx + sw and y > sy and y <= sy + sh
 end
 
+---@param x number
+---@param y number
+---@return boolean
 function View:scrollbar_track_overlaps_point(x, y)
   local sx, sy, sw, sh = self:get_scrollbar_track_rect()
   return x >= sx - style.scrollbar_size * 3 and x < sx + sw and y > sy and y <= sy + sh
 end
 
 
+---@param button core.view.mousebutton
+---@param x number
+---@param y number
+---@param clicks integer
+---return boolean
 function View:on_mouse_pressed(button, x, y, clicks)
   if self:scrollbar_track_overlaps_point(x, y) then
     if self:scrollbar_overlaps_point(x, y) then
@@ -125,11 +190,18 @@ function View:on_mouse_pressed(button, x, y, clicks)
 end
 
 
+---@param button core.view.mousebutton
+---@param x number
+---@param y number
 function View:on_mouse_released(button, x, y)
   self.dragging_scrollbar = false
 end
 
 
+---@param x number
+---@param y number
+---@param dx number
+---@param dy number
 function View:on_mouse_moved(x, y, dx, dy)
   if self.dragging_scrollbar then
     local delta = self:get_scrollable_size() / self.size.y * dy
@@ -150,15 +222,22 @@ function View:on_mouse_left()
 end
 
 
+---@param filename string
+---@param x number
+---@param y number
+---@return boolean
 function View:on_file_dropped(filename, x, y)
   return false
 end
 
 
+---@param text string
 function View:on_text_input(text)
   -- no-op
 end
 
+---@param y number
+---@return boolean
 function View:on_mouse_wheel(y)
 
 end
@@ -170,6 +249,8 @@ function View:get_content_bounds()
 end
 
 
+---@return number x
+---@return number y
 function View:get_content_offset()
   local x = common.round(self.position.x - self.scroll.x)
   local y = common.round(self.position.y - self.scroll.y)
@@ -213,6 +294,7 @@ function View:update()
 end
 
 
+---@param color renderer.color
 function View:draw_background(color)
   local x, y = self.position.x, self.position.y
   local w, h = self.size.x, self.size.y
diff --git a/data/plugins/treeview.lua b/data/plugins/treeview.lua
index 5bd57783..bdcb0f49 100644
--- a/data/plugins/treeview.lua
+++ b/data/plugins/treeview.lua
@@ -766,7 +766,7 @@ command.add(function() return treeitem() ~= nil end, {
     local text
     local item = treeitem()
     if not is_project_folder(item.abs_filename) then
-      text = treeitem().filename .. PATHSEP
+      text = item.filename .. PATHSEP
     end
     core.command_view:enter("Filename", {
       text = text,
@@ -789,7 +789,7 @@ command.add(function() return treeitem() ~= nil end, {
     local text
     local item = treeitem()
     if not is_project_folder(item.abs_filename) then
-      text = treeitem().filename .. PATHSEP
+      text = item.filename .. PATHSEP
     end
     core.command_view:enter("Folder Name", {
       text = text,