GNU bug report logs - #50903
Checkdoc recommendation for docstring subsitutions is inconsistent with other documentation

Previous Next

Full log

View this message in rfc822 format

From: help-debbugs <at> gnu.org (GNU bug Tracking System)
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: tracker <at> debbugs.gnu.org
Subject: bug#50903: closed (Checkdoc recommendation for docstring
 subsitutions is inconsistent with other documentation)
Date: Thu, 30 Sep 2021 16:27:01 +0000

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

Your message dated Thu, 30 Sep 2021 19:26:18 +0300
with message-id <83tui2f2s5.fsf <at> gnu.org>
and subject line Re: bug#50903: Checkdoc recommendation for docstring subsitutions is inconsistent with other documentation
has caused the debbugs.gnu.org bug report #50903,
regarding Checkdoc recommendation for docstring subsitutions is inconsistent with other documentation
to be marked as done.

(If you believe you have received this mail in error, please contact
help-debbugs <at> gnu.org.)


-- 
50903: http://debbugs.gnu.org/cgi/bugreport.cgi?bug=50903
GNU Bug Tracking System
Contact help-debbugs <at> gnu.org with problems

[Message part 2 (message/rfc822, inline)]

From: Nikolay Kudryavtsev <nikolay.kudryavtsev <at> gmail.com>
To: bug-gnu-emacs <at> gnu.org
Subject: Checkdoc recommendation for docstring subsitutions is inconsistent
 with other documentation
Date: Wed, 29 Sep 2021 22:46:14 +0300

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

I had a docstring containing "C-c". Checkdoc gave me this suggestion:
"Keycode C-c embedded in doc string.  Use \\<keymap> & \\[function] instead"

Ok, but how? The relevant page of Elisp reference is (info "(elisp) Keys 
in Documentation"). But there they're called ‘\<MAPVAR>’ and 
‘\[COMMAND]’. So someone searching by the checkdoc names would never 
find them there. The docstring for substitute-command-keys is also 
consistent with the Elisp reference.

A trivial patch is included, since Elisp reference names seem more 
reasonable.

I'm not sure whether MAPVAR and COMMAND should be capitalized in the 
docstring, so someone else should decide on that.

[0001-checkdoc-Docstring-substitution-consistent-with-othe.patch (text/plain, attachment)]

[Message part 5 (message/rfc822, inline)]

From: Eli Zaretskii <eliz <at> gnu.org>
To: Nikolay Kudryavtsev <nikolay.kudryavtsev <at> gmail.com>
Cc: 50903-done <at> debbugs.gnu.org
Subject: Re: bug#50903: Checkdoc recommendation for docstring subsitutions is
 inconsistent with other documentation
Date: Thu, 30 Sep 2021 19:26:18 +0300

> From: Nikolay Kudryavtsev <nikolay.kudryavtsev <at> gmail.com>
> Cc: 50903 <at> debbugs.gnu.org
> Date: Thu, 30 Sep 2021 16:35:59 +0300
> 
> Roger. s/r-d the patch.

Thanks, installed.

Previous Next

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