chore: add type annotations

[jamestrew]

trying something out.
I like types and I think it can help with our documentation deficiencies as well (eg. confusions around why you can pass default_text to find_files and why it's not documented, where to document it, etc, but this might need some enhancements to tree-sitter-lua since the newer luals luacats annotation support is limited).

[jamestrew]

this feels pretty ridiculous lol

[jamestrew]

don't like this

[jamestrew]

@Conni2461 what do you think?

[Conni2461]

i guess we can do that. i havent made up my mind regarding lua language servers annotations. they aren't compatible with emmylua annotations which are used within docgen (its uses a lua treesitter parser with emmylua support).

fyi there is also this: #1954

[jamestrew]

they aren't compatible with emmylua annotations which are used within docgen (its uses a lua treesitter parser with emmylua support).

Yeah I actually made an issue on tree-sitter-lua about (me) potentially adding or converting the ts grammar to support luals annotations.

I know this is something neovim core eventually would like for their docgen purposes as well. Somebody just needs to do it.

[jamestrew]

FYI I replaced telescope-file-browser's docgen with an alternative I've been working on.
HEAVILY based on neovim core's docgen script, integrating LuaCATS much more.

Looking to make a similar conversion for telescope core to enable changes like those in this PR.

nvim-telescope/telescope-file-browser.nvim#399

[clason]

FYI I replaced telescope-file-browser's docgen with an alternative I've been working on.
HEAVILY based on neovim core's docgen script, integrating LuaCATS much more.

This Is The Way. (There are now tree-sitter parsers for both luadoc and emmylua, so we don't have to choose between type checking and docgen.)

If this project is going to be actively developed in the future, strict annotations are a must IMO.

[clason]

(But maybe it makes sense to first pick a tool -- as a target, luals and emmyluals are broadly compatible -- and then start from scratch?)

[jamestrew]

I did also raise a PR a while back to switch out the docgen tool for telescope core too. #3227

I haven't kept up much with how neovim core is still doing docgen. It was all LuaCATS parsing with LPEG back when I converted the neovim docgen script into https://github.com/jamestrew/docgen.nvim
Main motivation for my docgen.nvim was

1. no dependencies (didn't want to require building treesitter parsers like we currently do with tj's tree-sitter-lua)
2. look and feel of generated help docs should be very close if not identical to neovim core
3. easy for plugins to use (main area where things start to differ from neovim core as their implementation has/had some bespoke rules/setup particular to neovim core)

I can take a look at giving it a refresh based on what neovim core is at today.

[clason]

If there's something core can expose through a refactor to make this easier for plugins, consider raising an issue! Plugin ecosystem health is something the team is taking quite seriously these days.

[clason]

@jamestrew is this superseded by #3227 ?

[jamestrew]

something like a second attempt #3670