RFC: Improvements of README or docs

[hrsh7th]

From past experience, I seem to be bad at writing documentation.

I would like to solicit opinions on the nvim-cmp documentation and what should be included in his README. (However, not all are adopted. I hate unnecessary or duplicate statements.)

google translated

[p0da]

I would actually say that right now the docs are in fairly good shape with the exception of some minor typos and stylistic issues here and there. If you really wanted to encourage more widespread usage of this plugin I'd say that some more beginner friendly documentation might be a good idea. However definitely don't add anything more to the README, the meat of the docs should go in the wiki/docs folder.

[YuvalHelman]

https://github.com/hrsh7th/nvim-cmp/pull/915

Would appreciate to know if this issue only persists for me or for other people. If also for other people, I still think it should be added to the default configuration in the README.

[kaiuri]

It looks awesome to me. But if one were to improve, starting out with an explanation on how everything fits together would've saved me some time. Really appreciate your interest, keep up this good work and thank you very much for nvim-cmp.

[Supreeeme]

Not necessarily in the README but some of the types used in the docs have no documentation. For example, cmp.SelectBehavior, cmp.ContextReason, cmp.ConfigSchema, cmp.ConfirmOption, and none of the stuff under cmp.mapping.preset is explained anywhere.

[camoz]

Related: https://github.com/hrsh7th/nvim-cmp/issues/1018

[raoulmillais]

First off thanks for an awesome project :heart: I'm a long time vim user now neovim user and have been using cmp for a while. I started out as I'm sure many did by copy/pasting and watching a video but I was setting up this + lsp + diagnostics + snippets at the same time. The last few days I've started trying to really understand it all and detangle things. Here's my initial observations:

• What does this plugin provide? (ghost text / completions / replacment pum / documentation window plus other things I haven't discovered yet!) IMO This should be right at the top of the README under the video.
• More detail about where it gets its sources from. Using null-ls together with this got me really confused about where things are coming from because it pumps its sources into LSP which then get picked up when cmp is configured with the lsp source.
• The docs refer to types (eg. cmp.SourceConfig) but these don't link anywhere and there's no way quick way to find out what their members are or how they are used without looking at the source
• How does formatting actually work? I had to look at the source to understand cmp.Entry to understand this. Maybe a separate wiki page for this would be helpful?

[Shougo]

I think the Pull Request wellcome.

[gbroques]

Explaining the sorting.comparators would be helpful.

This has been brought up in a previous issue, https://github.com/hrsh7th/nvim-cmp/issues/152, and the documentation request was declined since it's an "advanced feature".

However, I would encourage you to reconsider.

Other people, including myself, have wondered about these sorting.comparators for either two reasons:

1. to change the default sorting
2. or to understand the default sorting.

For example, there's discusson on Reddit about this feature:

• https://www.reddit.com/r/neovim/comments/u3c3kw/how_do_you_sorting_cmp_completions_items/
• https://www.reddit.com/r/neovim/comments/1115ow2/need_some_help_with_cmp_suggestion_priority_order/

One user in the first thread states:

I am confused. ... What the comparators does?

If I read the source code, then it's not really clear. For example, what does offset do? https://github.com/hrsh7th/nvim-cmp/blob/e28fb7a730b1bd425fdddfdbd3d36bb84bd77611/lua/cmp/config/compare.lua#L6-L14

I have to read and understand the Lua code, instead of having a high-level English description of what each comparator does.

Personally, the latter is easier and quicker to understand.

We don't have to explain these in the doc/ or even include more helpful comments in the source code.

There's a user named Yuki Uthman on YouTube who's made a helpful nvim-cmp playlist: https://www.youtube.com/watch?v=3O5aoxpdwqI&list=PLOe6AggsTaVuIXZU4gxWJpIQNHMrDknfN

Videos 23 - 26 discuss what some of these built-in comparators do, and a demo of them (Ctrl + F for "nvim cmp sorting" in the playlist).

Is it worth linking to external resources made by the community for "advanced" topics like this if we don't want to document them in the project?

P.S. Thank you for your work on nvim-cmp. It's a great and useful plugin for Neovim!! 👏

[hrsh7th]

Very good idea. The video is very useful.