Documenting new refactors, naming, and mnemonics.

[snoe]

I wanted to make a note of a higher level principal that I've never articulated that should be maintained as new functionality is added.

clj-refactor.el describes it:

All functions in clj-refactor have a two-letter mnemonic shortcut. E.g. rs for cljr-rename-symbol

Their list of two-letter commands is here: https://github.com/clojure-emacs/clj-refactor.el/wiki#available-refactorings

I believe that so far, two-letter mnemonic shortcuts in clojure-lsp have either been copied from clj-refactor or are still compatible with this scheme. But, as new commands are added, we should assign them a mnemonic name and two-letter code (e.g. promote-anonymous : pa) and document these all somewhere like https://github.com/clojure-lsp/clojure-lsp/blob/master/docs/features.md.

Keeping the same mnemonics as clj-refactor, helps muscle memory for anyone who switches over and can help drive a community standard if others want to write refactor tools. Publishing our list of functions and mnemonic codes can also help editors/plugins like helm or spacemacs have consistent shortcuts to our refactorings so that people who switch editors don't have to relearn shortcuts.

[ericdallo]

@snoe I'm not sure I got it, almost all refactors are available via code actions, which one can choose via shortcuts too, IMO calling refactors manually is not a good idea as calling a cycle-privacy on a not a function would not work, but via code actions clojure-lsp would not even suggest that code action.

Also, there is no mnemonics on LSP, this is all LSP client responsibility right? like for emacs we have SPC c a for lsp-execute-code-action, but the server has nothing related to that, am I missing something?

[snoe]

This is unrelated to code actions they aren't and shouldn't be the only way to execute things. For instance, I much prefer set bindings as code-actions jump around (clients seem to shortcut to numbers but 1 could be cycle-privacy in one place or rename in another).

For instance, in vim it's much more natural to me to have a chord bound like <leader>crcp (clojure refactor+cycle-privacy).

So I don't think the server code changes (unless code-actions can suggest shortcut keys), but documentation and conversation about existing and new functionality should specify the suggested mnemonics.

[ericdallo]

No problem, it makes sense to still make available, it's just that mention mnemonics on clojure-lsp side doesn't makes sense to me, this sounds to me like a thing clients should do not the server

[snoe]

Right, it is for clients to implement, but I believe we can publish and maintain a standard to help clients be consistent.

If I switch from vim to spacemacs to calva, I as a user, would like the two-letter code for an action be the same (if the editor supports such bindings) and the name of the action to be consistent.

So this is a way for us to encourage that consistency across clients by exposing this same principle that clj-refactor upheld. Hit me up on clojurians if the benefit's still not clear.

[ericdallo]

I see, In my experience, I doubt clients will follow that as it's pretty uncommon the bindings from Vscode match with vim or emacs for example, but we can do our best to suggest what we think it's best, so a section on features.md sounds reasonable

[snoe]

I see, In my experience, I doubt clients will follow that as it's pretty uncommon the bindings from Vscode match with vim or emacs for example, but we can do our best to suggest what we think it's best, so a section on features.md sounds reasonable

#871 updated the documentation.

@ericdallo @mainej The last point that I would like to drive home, is that new commands (feature/refactoring) should specify the command name and the two letter initial. I don't know if that's something that maintainers just need to be aware of or also a change in the github templates. If the new command's name or initials conflicts with an existing one we should try and find a different (even if slightly worse) name. If the idea (even if inexact implementation) is already existent in clj-refactor or cursive or wherever we should prefer those names. change-collection is a good example of what we want to avoid as that conflicted with cycle-collection [cc].

[ericdallo]

I totally ok with that, and understand that mnemonics are a good idea. I'm ok documenting that as well, but as @mainej mentioned on the pr recently, I think we should highlight code actions more than manually executing commands, as code actions tend to be more IDEish and have smart defaults of knowing when it should be suggested, WDYT?

[ericdallo]

I think latest documentation already mention the command + the mnemonic, is that enough to close this issue @snoe or there is anything missing?