Please add some documentation in the code file

[rswgnu]

This seems like an interesting concept but it is hard to try out because the setup instructions are only here on Github and not in the source file downloaded via the Emacs package manager. Additionally, there are now helm-xref-* commands provided. If you used autoloads and added commands, this would be a lot simpler.

Once you bind the xref function to your function, it is unclear which xref commands are affected. If you have a few minutes to document these things, it would be helpful and will likely increase usage of your package.

I see how it works now though my expectation was that it would use helm's interface when I was entering the term for which to search, not just after xrefs are displayed. It would be much more interesting that way where you could see all the dynamic matches as you do in many other modes.
But then helm-etags-select does that already based on TAGS files. Does this help in any way more than that?

[brotzeit]

I'm not sure I understand everything. I can put the "docs" from the github page in the file, sure.

There are no commands because you have to invoke the xref commands. The package only provides a different xref-show-xrefs-function. There's no need for commands. Unless there have been updates to xref I don't know yet.

I see how it works now though my expectation was that it would use helm's interface when I was entering the term for which to search, not just after xrefs are displayed. It would be much more interesting that way where you could see all the dynamic matches as you do in many other modes.

Which xref commands do you use ? If you use xref-find-references on a "thing" at your cursor, you get your references immediately. If xref can't grab a known "thing" you get a prompt that allows you to choose one. Then you get your occurrences of that "thing".

[rswgnu]

I'm not sure I understand everything. I can put the "docs" from the github page in the file, sure.

In the code commentary section, you want to document what it does from a user perspective. What will be different to the user after loading/autoloading this package. Even though this just modifies the behavior of existing xref commands, you want to explain how these commands and specifically which prompts in these commands will behave differently. You can say things like, "when xref-find-definitions, finds more than one match, it will use helm to select from the list of matches".

There are no commands because you have to invoke the xref commands. The package only provides a different xref-show-xrefs-function. There's no need for commands. Unless there have been updates to xref I don't know yet.

Of course, a new user won't know this, so it is worth explaining as well. It is very rare for an Emacs package to not add any new commands.

I see how it works now though my expectation was that it would use helm's interface when I was entering the term for which to search, not just after xrefs are displayed. It would be much more interesting that way where you could see all the dynamic matches as you do in many other modes.

Which xref commands do you use ?
I use xref-find-definitions and xref-find-references, I believe.

If you use xref-find-references on a "thing" at your cursor, you get your references immediately. If xref can't grab a known "thing" you get a prompt that allows you to choose one.

But helm is not used with the tags-table-list to prompt for which tag to select. That is the behavior I was expecting by default.

Then you get your occurrences of that "thing".

Yes, I see helm used after both a tag and a project is selected. I have a number of tags handling customization, so I may be seeing slightly different behavior than out-of-the-box Emacs has.

[brotzeit]

Sorry for the missing docs. I usually do a lot more for documentation ;)
I think this was my first package and there isn't much to it.

I will add something when I have finished the stuff I'm currently working on. However I would also gladly accept PRs =)

[rswgnu]

Sounds good.

[vjohansen]

I had the same confusion.

I suggest you write something like this

This package overrides how the xref functionality works in Emacs. When for example M-. (xref-find-definitions) is pressed and there are multiple values to select from then helm is used to show these

[brotzeit]

That's the purpose of helm, what did you expect ?

[vjohansen]

Most people conflate xref and (e)tags. Well, I do

When there is a package than is called helm-xxx many would think it is a new helm source with a function you need to bind to a key to use it.

helm itself comes with helm-etags so my first thought was it was similar (C-x c e).

The difference with your package is that uses the nice feature that xrefs behaviour can be changed by setting the xref-show-xrefs-function