GNU bug report logs - #17180
[PATCH] eldoc doesn't find docstrings for variable aliases

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 17180 in the body.
You can then email your comments to 17180 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Josh <josh <at> foxtail.org>
To: bug-gnu-emacs <at> gnu.org
Subject: [PATCH] eldoc doesn't find docstrings for variable aliases
Date: Thu, 3 Apr 2014 09:40:30 -0700

[Message part 1 (text/plain, inline)]

I noticed that eldoc doesn't currently show docstrings for variable
aliases such as `inhibit-splash-screen'.  The attached patch against
the eldoc.el in trunk fixes the behavior and also cleans up the
surrounding code a bit.  If the latter is objectionable, the only
functional change is passing `sym' through `indirect-variable' on the
way to `documentation-property' as `describe-variable' does.

Incidentally, I wondered whether this would be better addressed
within `documentation-property' itself but I wasn't sure it would be
correct to preclude the possibility of unique docstrings between
aliases and their targets.

=== modified file 'lisp/emacs-lisp/eldoc.el'
--- lisp/emacs-lisp/eldoc.el    2014-03-31 01:31:17 +0000
+++ lisp/emacs-lisp/eldoc.el    2014-04-03 16:14:43 +0000
@@ -418,18 +418,19 @@
 ;; Return a string containing a brief (one-line) documentation string for
 ;; the variable.
 (defun eldoc-get-var-docstring (sym)
-  (when sym
-    (cond ((and (eq sym (aref eldoc-last-data 0))
-               (eq 'variable (aref eldoc-last-data 2)))
-          (aref eldoc-last-data 1))
-         (t
-          (let ((doc (documentation-property sym 'variable-documentation
t)))
-            (cond (doc
-                   (setq doc (eldoc-docstring-format-sym-doc
-                              sym (eldoc-docstring-first-line doc)
-                              'font-lock-variable-name-face))
-                   (eldoc-last-data-store sym doc 'variable)))
-            doc)))))
+  (if (and (eq sym (aref eldoc-last-data 0))
+           (eq 'variable (aref eldoc-last-data 2)))
+      (aref eldoc-last-data 1)
+    (let ((doc
+           (documentation-property (indirect-variable sym)
+                                   'variable-documentation t)))
+      (when doc
+        (setq doc
+              (eldoc-docstring-format-sym-doc sym
+                                              (eldoc-docstring-first-line
doc)
+
'font-lock-variable-name-face))
+        (eldoc-last-data-store sym doc 'variable))
+      doc)))

 (defun eldoc-last-data-store (symbol doc type)
   (aset eldoc-last-data 0 symbol)

[Message part 2 (text/html, inline)]

Message #8 received at 17180 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Monnier <monnier <at> IRO.UMontreal.CA>
To: Josh <josh <at> foxtail.org>
Cc: 17180 <at> debbugs.gnu.org
Subject: Re: bug#17180: [PATCH] eldoc doesn't find docstrings for variable
 aliases
Date: Thu, 03 Apr 2014 13:37:05 -0400

> Incidentally, I wondered whether this would be better addressed
> within `documentation-property' itself

Yes, it should be fixed there directly.

> but I wasn't sure it would be correct to preclude the possibility of
> unique docstrings between aliases and their targets.

documentation-property should simply first check variable-documentation
and only when that fails, follow the alias indirection.


        Stefan

Message #17 received at 17180 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Stefan Monnier <monnier <at> IRO.UMontreal.CA>
Cc: Josh <josh <at> foxtail.org>, 17180 <at> debbugs.gnu.org
Subject: Re: bug#17180: [PATCH] eldoc doesn't find docstrings for variable
 aliases
Date: Wed, 26 Jun 2019 16:27:03 +0200

Stefan Monnier <monnier <at> IRO.UMontreal.CA> writes:

>> Incidentally, I wondered whether this would be better addressed
>> within `documentation-property' itself
>
> Yes, it should be fixed there directly.
>
>> but I wasn't sure it would be correct to preclude the possibility of
>> unique docstrings between aliases and their targets.
>
> documentation-property should simply first check variable-documentation
> and only when that fails, follow the alias indirection.

I've now implemented this like what's below, and I hope that's what you
meant.  :-)

diff --git a/src/doc.c b/src/doc.c
index 3fa0eaac20..bc05d09df4 100644
--- a/src/doc.c
+++ b/src/doc.c
@@ -436,8 +436,20 @@ DEFUN ("documentation-property", Fdocumentation_property,
  documentation_property:
 
   tem = Fget (symbol, prop);
+
+  /* If we don't have any documentation for this symbol, try to see whether
+     it's an indirect variable and get the documentation from there instead. */
+  if (NILP (tem))
+    {
+      Lisp_Object indirect = Findirect_variable (symbol);
+      if (!NILP (indirect))
+	tem = Fget (indirect, prop);
+    }
+
   if (EQ (tem, make_fixnum (0)))
     tem = Qnil;
+
+  /* See if we want to look for the string in the DOC file. */
   if (FIXNUMP (tem) || (CONSP (tem) && FIXNUMP (XCDR (tem))))
     {
       Lisp_Object doc = tem;


-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Message #24 received at 17180 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: Josh <josh <at> foxtail.org>, 17180 <at> debbugs.gnu.org
Subject: Re: bug#17180: [PATCH] eldoc doesn't find docstrings for variable
 aliases
Date: Wed, 26 Jun 2019 10:35:42 -0400

> +  /* If we don't have any documentation for this symbol, try to see whether
> +     it's an indirect variable and get the documentation from there instead. */
> +  if (NILP (tem))
> +    {
> +      Lisp_Object indirect = Findirect_variable (symbol);
> +      if (!NILP (indirect))
> +	tem = Fget (indirect, prop);
> +    }

In theory documentation-property can be used for any property, so it's
not necessarily specific to variables.  IOW I think we should only do
that if `prop` is `variable-documentation`.


        Stefan

Message #27 received at 17180 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: Josh <josh <at> foxtail.org>, 17180 <at> debbugs.gnu.org
Subject: Re: bug#17180: [PATCH] eldoc doesn't find docstrings for variable
 aliases
Date: Wed, 26 Jun 2019 16:37:05 +0200

Stefan Monnier <monnier <at> iro.umontreal.ca> writes:

>> +  /* If we don't have any documentation for this symbol, try to see whether
>> + it's an indirect variable and get the documentation from there
>> instead. */
>> +  if (NILP (tem))
>> +    {
>> +      Lisp_Object indirect = Findirect_variable (symbol);
>> +      if (!NILP (indirect))
>> +	tem = Fget (indirect, prop);
>> +    }
>
> In theory documentation-property can be used for any property, so it's
> not necessarily specific to variables.  IOW I think we should only do
> that if `prop` is `variable-documentation`.

Ah, makes sense.  I'll fix that up...

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.