chore: add type annotations

doc/telescope.txt

@@ -797,12 +797,8 @@ options you want to use. Here's an example with the live_grep picker:
   })
 <
 
-builtin.live_grep({opts})                      *telescope.builtin.live_grep()*
-    Search for a string and get results live as you type, respects .gitignore
-
-
-    Parameters: ~
-        {opts} (table)  options to pass to the picker
+TelescopeLiveGrepOpts                                  *TelescopeLiveGrepOpts*
+    TelescopeBasePickerOpts
 
     Options: ~
         {cwd}                 (string)          root dir to search from
@@ -812,7 +808,7 @@ builtin.live_grep({opts})                      *telescope.builtin.live_grep()*
         {grep_open_files}     (boolean)         if true, restrict search to
                                                 open files only, mutually
                                                 exclusive with `search_dirs`
-        {search_dirs}         (table)           directory/directories/files to
+        {search_dirs}         (string[])        directory/directories/files to
                                                 search, mutually exclusive
                                                 with `grep_open_files`
         {glob_pattern}        (string|table)    argument to be used with
@@ -829,6 +825,15 @@ builtin.live_grep({opts})                      *telescope.builtin.live_grep()*
                                                 numbers (default: false)
         {file_encoding}       (string)          file encoding for the entry &
                                                 previewer
+        {vimgrep_arguments}   (string[])        cmd to use for the search
+
+
+builtin.live_grep({opts})                      *telescope.builtin.live_grep()*
+    Search for a string and get results live as you type, respects .gitignore
+
+
+    Parameters: ~
+        {opts} (TelescopeLiveGrepOpts)  options to pass to the picker
 
 
 builtin.grep_string({opts})                  *telescope.builtin.grep_string()*

lua/telescope/builtin/__files.lua

@@ -105,10 +105,9 @@ local opts_contain_invert = function(args)
   return invert, files_with_matches
 end
 
--- Special keys:
---  opts.search_dirs -- list of directory to search in
---  opts.grep_open_files -- boolean to restrict search to open files
+---@param opts? TelescopeLiveGrepOpts
 files.live_grep = function(opts)
+  opts = opts or {}
   local vimgrep_arguments = opts.vimgrep_arguments or conf.vimgrep_arguments
   if not has_rg_program("live_grep", vimgrep_arguments[1]) then
     return

lua/telescope/builtin/init.lua

@@ -1,3 +1,5 @@
+---@diagnostic disable: undefined-doc-param
+
 ---@tag telescope.builtin
 
 ---@config { ['field_heading'] = "Options", ["module"] = "telescope.builtin" }
@@ -45,17 +47,21 @@ end
 --
 --
 
---- Search for a string and get results live as you type, respects .gitignore
----@param opts table: options to pass to the picker
+---@class TelescopeLiveGrepOpts : TelescopeBasePickerOpts
 ---@field cwd string: root dir to search from (default: cwd, use utils.buffer_dir() to search relative to open buffer)
 ---@field grep_open_files boolean: if true, restrict search to open files only, mutually exclusive with `search_dirs`
----@field search_dirs table: directory/directories/files to search, mutually exclusive with `grep_open_files`
+---@field search_dirs string[]: directory/directories/files to search, mutually exclusive with `grep_open_files`
 ---@field glob_pattern string|table: argument to be used with `--glob`, e.g. "*.toml", can use the opposite "!*.toml"
 ---@field type_filter string: argument to be used with `--type`, e.g. "rust", see `rg --type-list`
 ---@field additional_args function|table: additional arguments to be passed on. Can be fn(opts) -> tbl
 ---@field max_results number: define a upper result value
 ---@field disable_coordinates boolean: don't show the line & row numbers (default: false)
 ---@field file_encoding string: file encoding for the entry & previewer
+---@field vimgrep_arguments string[]: cmd to use for the search
+---@field [string] any
+
+--- Search for a string and get results live as you type, respects .gitignore
+---@param opts TelescopeLiveGrepOpts: options to pass to the picker
 builtin.live_grep = require_on_exported_call("telescope.builtin.__files").live_grep
 
 --- Searches for the string under your cursor or the visual selection in your current working directory

lua/telescope/entry_manager.lua

@@ -2,6 +2,12 @@ local log = require "telescope.log"
 
 local LinkedList = require "telescope.algos.linked_list"
 
+---@class TelescopeEntryManager
+---@field linked_states any
+---@field info any
+---@field max_results any
+---@field set_entry any
+---@field worst_acceptable_score any
 local EntryManager = {}
 EntryManager.__index = EntryManager
 

lua/telescope/finders.lua

@@ -7,6 +7,10 @@ local async_static_finder = require "telescope.finders.async_static_finder"
 local async_oneshot_finder = require "telescope.finders.async_oneshot_finder"
 local async_job_finder = require "telescope.finders.async_job_finder"
 
+---@class Finder
+---@field results table
+---@field close fun()
+
 local finders = {}
 
 local _callable_obj = function()

lua/telescope/pickers.lua

@@ -51,7 +51,7 @@ local ns_telescope_prompt_prefix = a.nvim_create_namespace "telescope_prompt_pre
 -- 2. Options window
 -- 3. Preview window
 --
----@param picker Picker
+---@param picker TelescopeBasePicker
 local function default_create_layout(picker)
   local function make_border(border)
     if not border then
@@ -215,13 +215,107 @@ local pickers = {}
 
 -- TODO: Add overscroll option for results buffer
 
----@class Picker
+---@class TelescopeBasePickerOpts
+---@field prompt_title string?
+---@field results_title string?
+---@field preview_title string?
+---@field prompt_prefix string?
+---@field wrap_results boolean?
+---@field selection_caret string?
+---@field entry_prefix string?
+---@field multi_icon string?
+---@field initial_mode ('insert'|'normal')?
+---@field debounce number?
+---@field default_text string?
+---@field get_status_text (fun(picker: TelescopeBasePicker): string)?
+---@field on_input_filter_cb (fun(prompt: string): any)?
+---@field finder Finder?
+---@field sorter Sorter?
+---@field previewer (Previewer[])?
+---@field current_previewer_index number?
+---@field default_selection_index number?
+---@field get_selection_window (fun(picker: TelescopeBasePicker, entry: table): number)?
+---@field cwd string?
+---@field _completion_callbacks ((fun(picker: TelescopeBasePicker): nil)[])?
+---@field manager TelescopeEntryManager?
+---@field _multi MultiSelect?
+---@field track boolean?
+---@field attach_mappings (fun(prompt_bufnr: integer, map: fun()): boolean)?
+---@field file_ignore_patterns (string[])?
+---@field scroll_strategy ('cycle'|'limit')?
+---@field sorting_strategy ('descending'|'ascending')?
+---@field tiebreak (fun(current_entry: any, existing_entry: any, prompt: string): boolean)?
+---@field selection_strategy ('reset'|'follow'|'row'|'closest'|'none')?
+---@field push_cursor_on_edit boolean?
+---@field push_tagstack_on_edit boolean?
+---@field layout_strategy ('horizontal'|'vertical'|'center'|'cursor'|'flex'|'bottom_pane')?
+---@field layout_config table?
+---@field cycle_layout_list (string[])?
+---@field winblend number?
+---@field window table?
+---@field border boolean?
+---@field borderchars (string[])?
+---@field cache_picker table?
+---@field private temp__scrolling_limit number?
+---@field create_layout fun()?
+---@field get_window_options fun()?
+---@field resumed_picker boolean?
+---@field fix_preview_title boolean?
+---@field private __hide_previewer boolean?
+---@field on_complete ((fun(picker: TelescopeBasePicker): nil)[])?
+
 --- Picker is the main UI that shows up to interact w/ your results.
 -- Takes a filter & a previewer
+---@class TelescopeBasePicker
+---@field prompt_title string
+---@field results_title string
+---@field preview_title string
+---@field prompt_prefix string
+---@field wrap_results boolean
+---@field selection_caret string
+---@field entry_prefix string
+---@field multi_icon string
+---@field initial_mode 'insert'|'normal'
+---@field private _original_mode string
+---@field debounce number?
+---@field private _finder_attached boolean
+---@field default_text string
+---@field get_status_text fun(self: TelescopeBasePicker): string
+---@field private _on_input_filter_cb fun(prompt: string): table
+---@field finder Finder
+---@field sorter Sorter
+---@field all_previewers Previewer[]
+---@field current_previewer_index number
+---@field default_selection_index number?
+---@field get_selection_window fun(self: TelescopeBasePicker, entry: table): number
+---@field cwd string?
+---@field private _find_id number
+---@field private _completion_callbacks (fun(self: TelescopeBasePicker): nil)[]
+---@field manager TelescopeEntryManager
+---@field private _multi MultiSelect
+---@field track boolean
+---@field stats table
+---@field attach_mappings? fun(prompt_bufnr: integer, map: fun()): boolean
+---@field file_ignore_patterns string[]
+---@field scroll_strategy 'cycle'|'limit'
+---@field sorting_strategy 'descending'|'ascending'
+---@field tiebreak fun(current_entry: any, existing_entry: any, prompt: string): boolean
+---@field selection_strategy 'reset'|'follow'|'row'|'closest'|'none'
+---@field push_cursor_on_edit boolean
+---@field push_tagstack_on_edit boolean
+---@field layout_strategy 'horizontal'|'vertical'|'center'|'cursor'|'flex'|'bottom_pane'
+---@field private __cycle_layout_list string[]
+---@field winblend number
+---@field window table
+---@field cache_picker table
+---@field scroller TelescopeScroller
+---@field highlighter TelescopeHighlighter
 local Picker = {}
 Picker.__index = Picker
 
 --- Create new picker
+---@param opts TelescopeBasePickerOpts
+---@return TelescopeBasePicker
 function Picker:new(opts)
   opts = opts or {}
 
@@ -243,8 +337,6 @@ function Picker:new(opts)
   --   pcall(v.clear)
   -- end
 
-  local layout_strategy = vim.F.if_nil(opts.layout_strategy, config.values.layout_strategy)
-
   local obj = setmetatable({
     prompt_title = vim.F.if_nil(opts.prompt_title, config.values.prompt_title),
     results_title = vim.F.if_nil(opts.results_title, config.values.results_title),
@@ -299,7 +391,7 @@ function Picker:new(opts)
     push_cursor_on_edit = vim.F.if_nil(opts.push_cursor_on_edit, false),
     push_tagstack_on_edit = vim.F.if_nil(opts.push_tagstack_on_edit, false),
 
-    layout_strategy = layout_strategy,
+    layout_strategy = vim.F.if_nil(opts.layout_strategy, config.values.layout_strategy),
     layout_config = config.smarter_depth_2_extend(opts.layout_config or {}, config.values.layout_config or {}),
 
     __cycle_layout_list = vim.F.if_nil(opts.cycle_layout_list, config.values.cycle_layout_list),
@@ -319,12 +411,11 @@ function Picker:new(opts)
     cache_picker = config.resolve_table_opts(opts.cache_picker, vim.deepcopy(config.values.cache_picker)),
 
     __scrolling_limit = tonumber(vim.F.if_nil(opts.temp__scrolling_limit, 250)),
-
     __locations_input = vim.F.if_nil(opts.__locations_input, false),
-  }, self)
 
-  obj.create_layout = opts.create_layout or config.values.create_layout or default_create_layout
-  obj.get_window_options = opts.get_window_options or p_window.get_window_options
+    create_layout = opts.create_layout or config.values.create_layout or default_create_layout,
+    get_window_options = opts.get_window_options or p_window.get_window_options,
+  }, self)
 
   if obj.all_previewers ~= nil and obj.all_previewers ~= false then
     if obj.all_previewers[1] == nil then
@@ -451,7 +542,7 @@ end
 
 --- Highlight the entry corresponding to the given row
 ---@param results_bufnr number: the buffer number of the results buffer
----@param prompt table: table with information about the prompt buffer
+---@param prompt string: table with information about the prompt buffer
 ---@param display string: the text corresponding to the given row
 ---@param row number: the number of the chosen row
 function Picker:highlight_one_row(results_bufnr, prompt, display, row)
@@ -506,7 +597,7 @@ function Picker:_next_find_id()
 end
 
 --- A helper function for creating each of the windows in a picker
----@param bufnr number: the buffer number to be used in the window
+---@param bufnr number|string: the buffer number to be used in the window
 ---@param popup_opts table: options to pass to `popup.create`
 function Picker:_create_window(bufnr, popup_opts)
   local what = bufnr or ""
@@ -999,7 +1090,7 @@ function Picker:reset_prompt(text)
   end
 end
 
----@param finder finder: telescope finder (see telescope/finders.lua)
+---@param finder Finder: telescope finder (see telescope/finders.lua)
 ---@param opts table: options to pass when refreshing the picker
 ---@field new_prefix string|table: either as string or { new_string, hl_group }
 ---@field reset_prompt bool: whether to reset the prompt
@@ -1507,7 +1598,7 @@ end
 --- with the telescope `defaults`
 ---@param opts table
 ---@param defaults table
----@return Picker
+---@return TelescopeBasePicker
 pickers.new = function(opts, defaults)
   opts = opts or {}
   defaults = defaults or {}
@@ -1620,6 +1711,7 @@ function pickers.on_resize_window(prompt_bufnr)
 end
 
 --- Get the prompt text without the prompt prefix.
+---@return string
 function Picker:_get_prompt()
   local cursor_line = vim.api.nvim_win_get_cursor(self.prompt_win)[1] - 1
   return vim.api

lua/telescope/pickers/highlights.lua

@@ -8,6 +8,8 @@ local ns_telescope_selection = a.nvim_create_namespace "telescope_selection"
 local ns_telescope_multiselection = a.nvim_create_namespace "telescope_multiselection"
 local ns_telescope_entry = a.nvim_create_namespace "telescope_entry"
 
+---@class TelescopeHighlighter
+---@field picker TelescopeBasePicker
 local Highlighter = {}
 Highlighter.__index = Highlighter
 

lua/telescope/pickers/multi.lua

@@ -1,3 +1,5 @@
+---@class MultiSelect
+---@field private _entries table
 local MultiSelect = {}
 MultiSelect.__index = MultiSelect
 

lua/telescope/pickers/scroller.lua

@@ -1,5 +1,7 @@
 local scroller = {}
 
+---@class TelescopeScroller
+
 local range_calculators = {
   ascending = function(max_results, num_results)
     return 0, math.min(max_results, num_results)

lua/telescope/previewers/previewer.lua

@@ -1,8 +1,23 @@
 local utils = require "telescope.utils"
 
+---@class Previewer
+---@field state table
+---@field private _title_fn TitleFn
+---@field private _dyn_title_fn TitleFn
+---@field private _setup_func any
+---@field private _teardown_func any
+---@field private _send_input any
+---@field private _scroll_fn any
+---@field private _scroll_horizontal_fn any
+---@field preview_fn any
+---@field private _empty_bufnr any
 local Previewer = {}
 Previewer.__index = Previewer
 
+---@alias TitleFn  fun(self:Previewer?, entry:table?): string
+
+---@param value string | fun(previewer: Previewer, entry: table): string
+---@return TitleFn | nil
 local force_function_wrap = function(value)
   if value ~= nil then
     if type(value) ~= "function" then