bug#17180: [PATCH] eldoc doesn't find docstrings for variable aliases

bug#17180: [PATCH] eldoc doesn't find docstrings for variable aliases

[Josh]

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

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)

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

bug#17180: [PATCH] eldoc doesn't find docstrings for variable aliases

[Stefan Monnier]

> 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

bug#17180: [PATCH] eldoc doesn't find docstrings for variable aliases

[Lars Ingebrigtsen]

Stefan Monnier <monnier@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

bug#17180: [PATCH] eldoc doesn't find docstrings for variable aliases

[Stefan Monnier]

> +  /* 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

bug#17180: [PATCH] eldoc doesn't find docstrings for variable aliases

[Lars Ingebrigtsen]

Stefan Monnier <monnier@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