nvim-plugins/aerial.nvim
1
0
Fork 0
mirror of https://github.com/stevearc/aerial.nvim synced 2024-09-16 14:34:08 +02:00
Code Issues Projects Releases Packages Wiki Activity

doc: better type annotations for API methods

Browse source
This commit is contained in:
Steven Arcangeli 2024-05-21 21:25:02 -07:00
parent 97a838ccc0
commit bd5f141a54
4 changed files with 50 additions and 42 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

20
doc/aerial.txt
View file

@ -452,10 +452,11 @@ open({opts}) *aerial.ope
Open the aerial window for the current buffer. Open the aerial window for the current buffer.
Parameters: Parameters:
{opts} `nil|table` {opts} `nil|aerial.openOpts`
{focus} `boolean` If true, jump to aerial window if it is opened {focus} `nil|boolean` If true, jump to aerial window if it is
(default true) opened (default true)
{direction} `"left"|"right"|"float"` Direction to open aerial window {direction} `nil|"left"|"right"|"float"` Direction to open aerial
window
open_in_win({target_win}, {source_win}) *aerial.open_in_win* open_in_win({target_win}, {source_win}) *aerial.open_in_win*
Open aerial in an existing window Open aerial in an existing window
@ -479,10 +480,11 @@ toggle({opts}) *aerial.toggl
Open or close the aerial window for the current buffer. Open or close the aerial window for the current buffer.
Parameters: Parameters:
{opts} `nil|table` {opts} `nil|aerial.openOpts`
{focus} `boolean` If true, jump to aerial window if it is opened {focus} `nil|boolean` If true, jump to aerial window if it is
(default true) opened (default true)
{direction} `"left"|"right"|"float"` Direction to open aerial window {direction} `nil|"left"|"right"|"float"` Direction to open aerial
window
refetch_symbols({bufnr}) *aerial.refetch_symbols* refetch_symbols({bufnr}) *aerial.refetch_symbols*
Refresh the symbols for a buffer Refresh the symbols for a buffer
@ -498,7 +500,7 @@ select({opts}) *aerial.selec
Jump to a specific symbol. Jump to a specific symbol.
Parameters: Parameters:
{opts} `nil|table` {opts} `nil|aerial.selectOpts`
{index} `nil|integer` The symbol to jump to. If nil, will jump to the {index} `nil|integer` The symbol to jump to. If nil, will jump to the
symbol under the cursor (in the aerial buffer) symbol under the cursor (in the aerial buffer)
{split} `nil|string` Jump to the symbol in a new split. Can be "v" for {split} `nil|string` Jump to the symbol in a new split. Can be "v" for

20
doc/api.md
View file

@ -92,10 +92,10 @@ Close all visible aerial windows except for the one currently focused or for the
Open the aerial window for the current buffer. Open the aerial window for the current buffer.
| Param | Type | Desc | | | Param | Type | Desc | |
| ----- | ------------ | -------------------------- | ------------------------------------------------------------- | | ----- | ---------------------- | ------------------------------- | ------------------------------------------------------------- |
| opts | `nil\|table` | | | | opts | `nil\|aerial.openOpts` | | |
| | focus | `boolean` | If true, jump to aerial window if it is opened (default true) | | | focus | `nil\|boolean` | If true, jump to aerial window if it is opened (default true) |
| | direction | `"left"\|"right"\|"float"` | Direction to open aerial window | | | direction | `nil\|"left"\|"right"\|"float"` | Direction to open aerial window |
## open_in_win(target_win, source_win) ## open_in_win(target_win, source_win)
@ -130,10 +130,10 @@ Jump to the aerial window for the current buffer, if it is open
Open or close the aerial window for the current buffer. Open or close the aerial window for the current buffer.
| Param | Type | Desc | | | Param | Type | Desc | |
| ----- | ------------ | -------------------------- | ------------------------------------------------------------- | | ----- | ---------------------- | ------------------------------- | ------------------------------------------------------------- |
| opts | `nil\|table` | | | | opts | `nil\|aerial.openOpts` | | |
| | focus | `boolean` | If true, jump to aerial window if it is opened (default true) | | | focus | `nil\|boolean` | If true, jump to aerial window if it is opened (default true) |
| | direction | `"left"\|"right"\|"float"` | Direction to open aerial window | | | direction | `nil\|"left"\|"right"\|"float"` | Direction to open aerial window |
## refetch_symbols(bufnr) ## refetch_symbols(bufnr)
@ -156,8 +156,8 @@ call this if you change something in the config (e.g. by setting vim.b.aerial_ba
Jump to a specific symbol. Jump to a specific symbol.
| Param | Type | Desc | | | Param | Type | Desc | |
| ----- | ------------ | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | ----- | ------------------------ | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| opts | `nil\|table` | | | | opts | `nil\|aerial.selectOpts` | | |
| | index | `nil\|integer` | The symbol to jump to. If nil, will jump to the symbol under the cursor (in the aerial buffer) | | | index | `nil\|integer` | The symbol to jump to. If nil, will jump to the symbol under the cursor (in the aerial buffer) |
| | split | `nil\|string` | Jump to the symbol in a new split. Can be "v" for vertical or "h" for horizontal. Can also be a raw command to execute (e.g. "belowright split") | | | split | `nil\|string` | Jump to the symbol in a new split. Can be "v" for vertical or "h" for horizontal. Can also be a raw command to execute (e.g. "belowright split") |
| | jump | `nil\|boolean` | If false and in the aerial window, do not leave the aerial window. (Default true) | | | jump | `nil\|boolean` | If false and in the aerial window, do not leave the aerial window. (Default true) |

22
lua/aerial/init.lua
View file

@ -261,10 +261,12 @@ M.close_all = lazy("window", "close_all")
---Close all visible aerial windows except for the one currently focused or for the currently focused window. ---Close all visible aerial windows except for the one currently focused or for the currently focused window.
M.close_all_but_current = lazy("window", "close_all_but_current") M.close_all_but_current = lazy("window", "close_all_but_current")
---@class (exact) aerial.openOpts
---@field focus? boolean If true, jump to aerial window if it is opened (default true)
---@field direction? "left"|"right"|"float" Direction to open aerial window
---Open the aerial window for the current buffer. ---Open the aerial window for the current buffer.
---@param opts? table ---@param opts? aerial.openOpts
--- focus boolean If true, jump to aerial window if it is opened (default true)
--- direction "left"|"right"|"float" Direction to open aerial window
M.open = function(opts) M.open = function(opts)
do_setup() do_setup()
was_closed = false was_closed = false
@ -293,9 +295,7 @@ M.open_all = lazy("window", "open_all")
M.focus = lazy("window", "focus") M.focus = lazy("window", "focus")
---Open or close the aerial window for the current buffer. ---Open or close the aerial window for the current buffer.
---@param opts? table ---@param opts? aerial.openOpts
--- focus boolean If true, jump to aerial window if it is opened (default true)
--- direction "left"|"right"|"float" Direction to open aerial window
M.toggle = function(opts) M.toggle = function(opts)
do_setup() do_setup()
opts = vim.tbl_extend("keep", opts or {}, { opts = vim.tbl_extend("keep", opts or {}, {
@ -327,11 +327,13 @@ M.refetch_symbols = function(bufnr)
end end
end end
---@class (exact) aerial.selectOpts
---@field index? integer The symbol to jump to. If nil, will jump to the symbol under the cursor (in the aerial buffer)
---@field split? string Jump to the symbol in a new split. Can be "v" for vertical or "h" for horizontal. Can also be a raw command to execute (e.g. "belowright split")
---@field jump? boolean If false and in the aerial window, do not leave the aerial window. (Default true)
---Jump to a specific symbol. ---Jump to a specific symbol.
---@param opts? table ---@param opts? aerial.selectOpts
--- index? integer The symbol to jump to. If nil, will jump to the symbol under the cursor (in the aerial buffer)
--- split? string Jump to the symbol in a new split. Can be "v" for vertical or "h" for horizontal. Can also be a raw command to execute (e.g. "belowright split")
--- jump? boolean If false and in the aerial window, do not leave the aerial window. (Default true)
M.select = lazy("navigation", "select", true) M.select = lazy("navigation", "select", true)
---Jump forwards in the symbol list. ---Jump forwards in the symbol list.

18
scripts/generate.py
View file

@ -13,11 +13,11 @@ from nvim_doc_tools import (
format_vimdoc_commands, format_vimdoc_commands,
generate_md_toc, generate_md_toc,
indent, indent,
parse_functions, parse_directory,
read_nvim_json, read_nvim_json,
read_section, read_section,
render_md_api, render_md_api2,
render_vimdoc_api, render_vimdoc_api2,
replace_section, replace_section,
) )
@ -61,8 +61,9 @@ def add_md_link_path(path: str, lines: List[str]) -> List[str]:
def update_md_api(): def update_md_api():
funcs = parse_functions(os.path.join(ROOT, "lua", "aerial", "init.lua")) types = parse_directory(os.path.join(ROOT, "lua"))
lines = ["\n"] + render_md_api(funcs, 2) + ["\n"] funcs = types.files["aerial/init.lua"].functions
lines = ["\n"] + render_md_api2(funcs, types, 2) + ["\n"]
api_doc = os.path.join(DOC, "api.md") api_doc = os.path.join(DOC, "api.md")
replace_section( replace_section(
api_doc, api_doc,
@ -138,12 +139,15 @@ def get_notes_vimdoc() -> "VimdocSection":
def generate_vimdoc(): def generate_vimdoc():
doc = Vimdoc("aerial.txt", "aerial") doc = Vimdoc("aerial.txt", "aerial")
funcs = parse_functions(os.path.join(ROOT, "lua", "aerial", "init.lua")) types = parse_directory(os.path.join(ROOT, "lua"))
funcs = types.files["aerial/init.lua"].functions
doc.sections.extend( doc.sections.extend(
[ [
get_options_vimdoc(), get_options_vimdoc(),
get_commands_vimdoc(), get_commands_vimdoc(),
VimdocSection("API", "aerial-api", render_vimdoc_api("aerial", funcs)), VimdocSection(
"API", "aerial-api", render_vimdoc_api2("aerial", funcs, types)
),
get_notes_vimdoc(), get_notes_vimdoc(),
] ]
) )