Suggestion for improved clarity in xref.el symbol names

Suggestion for improved clarity in xref.el symbol names

[Robert Weiner]

[-- Attachment #1: Type: text/plain, Size: 583 bytes --]

The xref.el library has many variables and functions with `backend' in
them, indicating that they represent language-dependent entities.  Before
the xref API is set in stone, I would consider replacing this term with
'language' as it reads better in the names, it refers to a concept
intrinsic to the cross-references themselves which are language-specific,
whereas backend is just an implementation detail, and it will make more
sense to users of the library who may not be familiar with the concept of a
`backend'.

Just a thought but I know these names will live for a long time.

[-- Attachment #2: Type: text/html, Size: 661 bytes --]

Re: Suggestion for improved clarity in xref.el symbol names

[John Wiegley]

[-- Attachment #1: Type: text/plain, Size: 997 bytes --]

>>>>> Robert Weiner <rswgnu@gmail.com> writes:

> The xref.el library has many variables and functions with `backend' in them,
> indicating that they represent language-dependent entities. Before the xref
> API is set in stone, I would consider replacing this term with 'language' as
> it reads better in the names, it refers to a concept intrinsic to the
> cross-references themselves which are language-specific, whereas backend is
> just an implementation detail, and it will make more sense to users of the
> library who may not be familiar with the concept of a `backend'.

> Just a thought but I know these names will live for a long time.

Note that in Emacs 25, xref is still going to be considered "experimental",
and I believe Dmitry has documented it as such, meaning they won't be cast in
as firm a stone as usual.

-- 
John Wiegley                  GPG fingerprint = 4710 CF98 AF9B 327B B80F
http://newartisans.com                          60E1 46C4 BD1A 7AC1 4BA2

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 629 bytes --]

Re: Suggestion for improved clarity in xref.el symbol names

[Dmitry Gutov]

Hello Robert,

On 04/19/2016 11:27 PM, Robert Weiner wrote:
> The xref.el library has many variables and functions with `backend' in
> them, indicating that they represent language-dependent entities.
> Before the xref API is set in stone, I would consider replacing this
> term with 'language' as it reads better in the names,

Thanks for the suggestion, but a backend is not a language, it's a 
particular solution for a given language and/or environment.

There will (hopefully) be multiple different backends for certain 
languages. There can be backends that are specific to a certain 
environment within a language (say, only projects using a particular 
framework), and so on.

A backend can also be language-agnostic. In fact, one of the two 
backends available now is that (etags).

> it refers to a
> concept intrinsic to the cross-references themselves which are
> language-specific, whereas backend is just an implementation detail, and
> it will make more sense to users of the library who may not be familiar
> with the concept of a `backend'.

The functions and variables with the word "backend" in them are normally 
something only backend authors should be concerned with. And they should 
get familiar with the concept, because xref-backend-functions is the 
main entry point to this API. I'm not sure the phrase "xref language" 
could convey the same notion.

The user-level commands don't have the word "backend" in them.