From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Robert Weiner Newsgroups: gmane.emacs.devel Subject: Re: xref rocks! Date: Tue, 26 Apr 2016 23:35:33 -0400 Message-ID: References: <87shy9apka.fsf@petton.fr> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: multipart/alternative; boundary=94eb2c09b194ec56e005316f1b80 X-Trace: ger.gmane.org 1461728191 26704 80.91.229.3 (27 Apr 2016 03:36:31 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Wed, 27 Apr 2016 03:36:31 +0000 (UTC) Cc: emacs-devel To: Dmitry Gutov Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Wed Apr 27 05:36:30 2016 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1avGH8-00065M-2H for ged-emacs-devel@m.gmane.org; Wed, 27 Apr 2016 05:36:30 +0200 Original-Received: from localhost ([::1]:40569 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1avGH7-0002B4-B2 for ged-emacs-devel@m.gmane.org; Tue, 26 Apr 2016 23:36:29 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:39958) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1avGGn-000210-5W for emacs-devel@gnu.org; Tue, 26 Apr 2016 23:36:14 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1avGGh-0000UV-Ta for emacs-devel@gnu.org; Tue, 26 Apr 2016 23:36:09 -0400 Original-Received: from mail-oi0-x231.google.com ([2607:f8b0:4003:c06::231]:34420) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1avGGh-0000UM-NR for emacs-devel@gnu.org; Tue, 26 Apr 2016 23:36:03 -0400 Original-Received: by mail-oi0-x231.google.com with SMTP id k142so36496836oib.1 for ; Tue, 26 Apr 2016 20:36:03 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=mime-version:in-reply-to:references:from:date:message-id:subject:to :cc; bh=cKBlj5BFRvvN+TnWbYxXapMruihacfIKnVxxmUI0VxM=; b=TpD4wyCTo1/RKHXXZ7uXFuNVfUIb33vZShRn9FeAQJxsSedZ2WYjjfQCPMtlvcwScs FaxpkC2PHx/Ecf0x+6si4+9aANnAqH4BxCxgCOSmFAyH0JjsHRMwXgdoMJNHU5gqpGdD XQvJgnSgO9P/OsbnpN8+FVg7wSTWVSXVfSPEVWH7hlSnMaeWGaR8nJ8q0WfDPB5UihBm 7mDeviamrOf1/crvUApAYcTCpovHqD/AImpOrWptdl7H2wQcOXQvQgMmU6tiqrhSxtqI gxB7gZdrmSdaYxckicDUjeXDZtf18mfYIctLOgD+FbCd42poJ1WcmQ3KUZsaZnEkoBg4 veuQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:mime-version:in-reply-to:references:from:date :message-id:subject:to:cc; bh=cKBlj5BFRvvN+TnWbYxXapMruihacfIKnVxxmUI0VxM=; b=ce0eKAAaA4K6VGSmDRsgnZpYdlWQ9tWmYstkKyG1Nnd9xgqX4XupuzcIagvqnpbwFh 1WgjG/SLeFW5sZRKw8twDCZ2pOcNvz9d//ipL+dWzjWGwhYK4g7ks3DaBlmpLn4/gOvP TwBVgTdQvFTqF3XAySGXSmsF5JyeENS5bjAo6zCN8D//ocAawpy8AgslyRxUuXiC98gL GwE2yyxc0QSIeDjd5ihp4rc8wpxjM7YDKB/pfxS33RCyrIll32SDMuypX0oma7fPdfCY TERyurgKNUoBIAbMzLshwIr3Z3tjmD8qSLvuxm5qXYOuHSZeTlQSC+n+eeJJyZLqHdPQ sstw== X-Gm-Message-State: AOPr4FUy5w9rq6ODg+6mTTwuK4R9+GEs09pn6crjuonLIq1omNvkl2+Fgz71d5ISTY+EIzJfky0PE9Nt0PZvrg== X-Received: by 10.157.25.137 with SMTP id k9mr2710459otk.131.1461728163156; Tue, 26 Apr 2016 20:36:03 -0700 (PDT) Original-Received: by 10.202.83.135 with HTTP; Tue, 26 Apr 2016 20:35:33 -0700 (PDT) In-Reply-To: X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 2607:f8b0:4003:c06::231 X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Original-Sender: "Emacs-devel" Xref: news.gmane.org gmane.emacs.devel:203372 Archived-At: --94eb2c09b194ec56e005316f1b80 Content-Type: text/plain; charset=UTF-8 On Tue, Apr 26, 2016 at 4:41 PM, Dmitry Gutov wrote: > On 04/26/2016 08:12 PM, Robert Weiner wrote: > > One thing that would help would be better >> separation between finding xrefs (which should just return lists of >> them) and displaying xrefs. For example, I went looking for a generic >> xref equivalent to find-tag-noselect and the only thing I found was >> something specific to elisp tags. >> > > Are you looking for > > (xref-backend-definitions (xref-find-backend) "car") > Yes, that is helpful. So why not include a wrapper for the API of something like: (xref-get-definitions "car") > > Also, there seem to be many functions that just call a single other >> functions, creating a deeply nested tree of calls. Is there a way to >> simplify that? >> > > Could you give an example? xref-find-definitions calls only xref--find-definitions which calls only xref--find-xrefs which essentially calls only xref--show-xrefs. > > I also see that about a year ago there was a call for documenting >> xref.el. Has any progress been made on that? Even though things will >> change, writing the documentation will give you a base that you can >> adapt as the library evolves and will help people to provide further >> feedback. >> > > There is an introduction in Commentary at the top of xref.el. You can read > it, among other ways, using `M-x describe-package RET xref RET'. > I have read it. It certainly points to many places in the package and in the backend implementations to look for more documentation but doesn't give a sense of how to use the package after defining a backend, i.e. what commands are available and what parameters do they require, or for programmers, what do the resulting API calls look like? Including a simple sample backend, much simpler than referencing the existing backends, would also help a lot to show the minimum involved in creating a backend. Think of someone who knows Elisp and Emacs but knows nothing about xrefs. Can you tell them 1. how to utilize existing backends and 2. how to create a backend in some detail. Just some thoughts. Bob --94eb2c09b194ec56e005316f1b80 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable
On T= ue, Apr 26, 2016 at 4:41 PM, Dmitry Gutov <dgutov@yandex.ru> = wrote:
On 04/26/2016 08:12 PM, Robert = Weiner wrote:

One thing that would help would be better
separation between finding xrefs (which should just return lists of
them) and displaying xrefs.=C2=A0 For example, I went looking for a generic=
xref equivalent to find-tag-noselect and the only thing I found was
something specific to elisp tags.
=C2=A0
Are you looking for
=C2=A0 =C2=A0(xref-backend-definitions (xref-find-backend) "car")=

Yes, that is helpful.=C2=A0 So why not= include a wrapper for the API of something like:
=C2=A0 =C2=A0(x= ref-get-definitions "car")

=

Also, there seem to be many functions that just call a single other
functions, creating a deeply nested tree of calls.=C2=A0 Is there a way to<= br> simplify that?

 Could you give an example?

xref-find-defini= tions calls only xref--find-definitions which calls
only xref--fi= nd-xrefs which essentially calls only xref--show-xrefs.=C2=A0


I also see that about a year ago there was a call for documenting
xref.el.=C2=A0 Has any progress been made on that?=C2=A0 Even though things= will
change, writing the documentation will give you a base that you can
adapt as the library evolves and will help people to provide further
feedback.

 There is an introduction in Commentary at the top of xref.el. You can read = it, among other ways, using `M-x describe-package RET xref RET'.

I have read it.=C2=A0 It certainly points to = many places in the package and in the backend implementations to look for m= ore documentation but doesn't give a sense of how to use the package af= ter defining a backend, i.e. what commands are available and what parameter= s do they require, or for programmers, what do the resulting API calls look= like?=C2=A0 Including a simple sample backend, much simpler than referenci= ng the existing backends, would also help a lot to show the minimum involve= d in creating a backend.=C2=A0 Think of someone who knows Elisp and Emacs b= ut knows nothing about xrefs.=C2=A0 Can you tell them 1. how to utilize exi= sting backends and 2. how to create a backend in some detail.
Just some thoughts.

Bob

=
--94eb2c09b194ec56e005316f1b80--