GNU bug report logs - #30025
26.0.90; [Documentation][26.1] Docstring for epa-pinentry-mode shows erroneous link

Previous Next

Package: emacs;

Reported by: Damien Cassou <damien <at> cassou.me>

Date: Mon, 8 Jan 2018 15:40:02 UTC

Severity: minor

Found in version 26.0.90

Done: Eli Zaretskii <eliz <at> gnu.org>

Bug is archived. No further changes may be made.

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

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

View this report as an mbox folder, status mbox, maintainer mbox

Report forwarded to bug-gnu-emacs <at> gnu.org:
bug#30025; Package emacs. (Mon, 08 Jan 2018 15:40:02 GMT) Full text and rfc822 format available.
Acknowledgement sent to Damien Cassou <damien <at> cassou.me>:
New bug report received and forwarded. Copy sent to bug-gnu-emacs <at> gnu.org. (Mon, 08 Jan 2018 15:40:02 GMT) Full text and rfc822 format available.

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

From: Damien Cassou <damien <at> cassou.me>
To: bug-gnu-emacs <at> gnu.org
Cc: rms <at> gnu.org
Subject: 26.0.90;
 [Documentation][26.1] Docstring for epa-pinentry-mode shows erroneous
 link
Date: Mon, 08 Jan 2018 16:39:01 +0100

How to reproduce:

1. C-h v epa-pinentry-mode RET

Expected: the word "error" should be represented as a keyword, not as a
  link

Actual: the word "error" is a link to the function of the same name.

The docstring of epa-pinentry-mode describes 4 possible symbols for the
value. These symbols only make sense in the context of the variable. In
particular, they are not function or variable names. Still, the word
error is represented as a link to the function of the same name.

What is best practice to describe symbols in docstring?

Best,

-- 
Damien Cassou
http://damiencassou.seasidehosting.st

"Success is the ability to go from one failure to another without
losing enthusiasm." --Winston Churchill
Reply sent to Eli Zaretskii <eliz <at> gnu.org>:
You have taken responsibility. (Mon, 08 Jan 2018 21:30:02 GMT) Full text and rfc822 format available.
Notification sent to Damien Cassou <damien <at> cassou.me>:
bug acknowledged by developer. (Mon, 08 Jan 2018 21:30:02 GMT) Full text and rfc822 format available.

Message #10 received at 30025-done <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Damien Cassou <damien <at> cassou.me>
Cc: 30025-done <at> debbugs.gnu.org, rms <at> gnu.org
Subject: Re: bug#30025: 26.0.90;
 [Documentation][26.1] Docstring for epa-pinentry-mode shows erroneous
 link
Date: Mon, 08 Jan 2018 23:28:40 +0200

> Date: Mon, 08 Jan 2018 16:39:01 +0100
> Cc: rms <at> gnu.org
> 
> How to reproduce:
> 
> 1. C-h v epa-pinentry-mode RET
> 
> Expected: the word "error" should be represented as a keyword, not as a
>   link
> 
> Actual: the word "error" is a link to the function of the same name.

Thanks, fixed.

> What is best practice to describe symbols in docstring?

You need to use a magic word ;-)  (It's all described in the node
"Documentation Tips" of the ELisp manual.)
bug archived. Request was from Debbugs Internal Request <help-debbugs <at> gnu.org> to internal_control <at> debbugs.gnu.org. (Tue, 06 Feb 2018 12:24:06 GMT) Full text and rfc822 format available.
This bug report was last modified 7 years and 192 days ago.

Previous Next

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