barrett/canola.nvim
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 4

doc: better type annotations for API methods

Browse source
This commit is contained in:
Steven Arcangeli 2024-05-21 19:39:37 -07:00
parent 06a19f77f1
commit 259b1fbc84
4 changed files with 21 additions and 15 deletions
Download patch file Download diff file Expand all files Collapse all files

2
doc/api.md
View file

@ -136,7 +136,7 @@ Select the entry under the cursor
| Param | Type | Desc | |
| -------- | ---------------------------- | -------------------------------------------------- | ---------------------------------------------------- |
| opts | `nil\|table` | | |
| opts | `nil\|oil.SelectOpts` | | |
| | vertical | `boolean` | Open the buffer in a vertical split |
| | horizontal | `boolean` | Open the buffer in a horizontal split |
| | split | `"aboveleft"\|"belowright"\|"topleft"\|"botright"` | Split modifier |

2
doc/oil.txt
View file

@ -311,7 +311,7 @@ select({opts}, {callback}) *oil.selec
Select the entry under the cursor
Parameters:
{opts} `nil|table`
{opts} `nil|oil.SelectOpts`
{vertical} `boolean` Open the buffer in a vertical split
{horizontal} `boolean` Open the buffer in a horizontal split
{split} `"aboveleft"|"belowright"|"topleft"|"botright"` Split

14
lua/oil/init.lua
View file

@ -539,13 +539,15 @@ M.open_preview = function(opts, callback)
end)
end
---@class (exact) oil.SelectOpts
---@field vertical boolean Open the buffer in a vertical split
---@field horizontal boolean Open the buffer in a horizontal split
---@field split "aboveleft"|"belowright"|"topleft"|"botright" Split modifier
---@field tab boolean Open the buffer in a new tab
---@field close boolean Close the original oil buffer once selection is made
---Select the entry under the cursor
---@param opts nil|table
--- vertical boolean Open the buffer in a vertical split
--- horizontal boolean Open the buffer in a horizontal split
--- split "aboveleft"|"belowright"|"topleft"|"botright" Split modifier
--- tab boolean Open the buffer in a new tab
--- close boolean Close the original oil buffer once selection is made
---@param opts nil|oil.SelectOpts
---@param callback nil|fun(err: nil|string) Called once all entries have been opened
M.select = function(opts, callback)
local cache = require("oil.cache")

18
scripts/generate.py
View file

@ -6,16 +6,18 @@ from typing import List
from nvim_doc_tools import (
LuaParam,
LuaTypes,
Vimdoc,
VimdocSection,
generate_md_toc,
indent,
leftright,
parse_directory,
parse_functions,
read_nvim_json,
read_section,
render_md_api,
render_vimdoc_api,
render_md_api2,
render_vimdoc_api2,
replace_section,
wrap,
)
@ -37,8 +39,9 @@ def add_md_link_path(path: str, lines: List[str]) -> List[str]:
def update_md_api():
api_doc = os.path.join(DOC, "api.md")
funcs = parse_functions(os.path.join(ROOT, "lua", "oil", "init.lua"))
lines = ["\n"] + render_md_api(funcs, 2) + ["\n"]
types = parse_directory(os.path.join(ROOT, "lua"))
funcs = types.files["oil/init.lua"].functions
lines = ["\n"] + render_md_api2(funcs, types, 2) + ["\n"]
replace_section(
api_doc,
r"^<!-- API -->$",
@ -264,7 +267,7 @@ def get_columns_vimdoc() -> "VimdocSection":
section.body.extend(wrap(col.summary, 4))
section.body.append("\n")
section.body.append(" Parameters:\n")
section.body.extend(format_vimdoc_params(col.params, 6))
section.body.extend(format_vimdoc_params(col.params, LuaTypes(), 6))
section.body.append("\n")
return section
@ -302,12 +305,13 @@ Windows:
def generate_vimdoc():
doc = Vimdoc("oil.txt", "oil")
funcs = parse_functions(os.path.join(ROOT, "lua", "oil", "init.lua"))
types = parse_directory(os.path.join(ROOT, "lua"))
funcs = types.files["oil/init.lua"].functions
doc.sections.extend(
[
get_options_vimdoc(),
get_options_detail_vimdoc(),
VimdocSection("API", "oil-api", render_vimdoc_api("oil", funcs)),
VimdocSection("API", "oil-api", render_vimdoc_api2("oil", funcs, types)),
get_columns_vimdoc(),
get_actions_vimdoc(),
get_highlights_vimdoc(),