-
-
Notifications
You must be signed in to change notification settings - Fork 851
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Docs doesn't make it clear that pickers and extensions accept same opts as defaults #3238
Comments
I agree, there's a lot to be desired in our help docs. There is a lot of inheritance with the options of the pickers and a lot of it is undocumented largely because with our current documentation generation tooling, there isn't a really clean, non-cumbersome way to express these inheritances. |
Thanks for the kind reply, really happy to help. |
Yeah if you're interested, by all means, I will welcome these clarifications. |
I'll make a PR soon if you're okay with it. Then, I will have the glory to have a PR named "Changed README" merged to my name, and I think that is a life-goal |
I've started writing my PR and I'm looking into setup and pickers code to make sure which keys are valid for pickers and which aren't. For this particular PR, I will propose only static changes to the docs, no additional code, but since defaults options are dynamically generated, I could add a lookup to see if the key is valid for pickers. It would involve something like this -- init.lua -- This is pseudocode
telescope.__format_setup_keys = function()
-- My first idea is having telescope.pickers have a list
-- of accepted options as a hint for the docs. This could be also a local table
-- in this function, as it's a temporary workaround
local picker_compatible_keys = require("telescope.pickers").__docs_get_valid_keys()
for _, name in ipairs(names) do
-- *snip* Current code that makes descriptions
if table.contains(picker_compatible_keys, name) then
description = description .. " (Picker compatible)"
end
end I don't know if that kind of code would be welcome? Otherwise I can just modify the defaults option description keys individually. What would be the proper way to indicate a key is "picker compatible"? That is my own terminology but there might be a proper term? How would you prefer I annotate such keys in the defaults description ? Depending on if there are more compatible keys, or more non-compatible, it may be preferable to rather another when a key is not compatible with pickers (so "Telescope Specific" you may say)
Please let me know what changes are welcome or not, and the direction you feel this should go in. EDIT: I could also try and implement the inheritance definition in the docgen tool if you're okay with it and if you think it's doable with intermediate knowledge of lua and neovim tools |
Description
I've been diving into telescope recently, as I've been using it for some time but never configured it thoroughly. I read the entire :h manual inside Neovim.
I hard a hard time understanding what options the individual pickers or extensions passed into setup() could take. It took me a while to understand that a picker's config table accepts the same keys as "defaults" table plus its own config keys which are shown in telescope.builtin. Writing it down I understand that it's kinda implied that defaults can be overriden, but it took me some time to fully get how it works.
Do you think this warrants a little clarification ?
In my humble opinion, it'd be worth modifying the telescope.setup section and the telescope.builtin section, here is my opinion on the parts the documentation is lacking clarity, as well as my humble proposal. I'd love to hear your feedbacks on this.
:h telescope.setup()
I have to note that the builtin part of the builtin help kinda implies this but it doesn't state it clearly. What I struggled to understand is that the builtin pickers options extend the default ones. Maybe this section could be clarified?
:h telescope.builtin
Neovim version
Operating system and version
Debian 12
Telescope version / branch / rev
0.1.X
checkhealth telescope
Steps to reproduce
Expected behavior
No response
Actual behavior
See desc
Minimal config
The text was updated successfully, but these errors were encountered: