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: Nikolay Kudryavtsev <nikolay.kudryavtsev <at> gmail.com>
Subject: bug#50903: closed (Re: bug#50903: Checkdoc recommendation for
 docstring subsitutions is inconsistent with other documentation)
Date: Thu, 30 Sep 2021 16:27:02 +0000

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

Your bug report

#50903: Checkdoc recommendation for docstring subsitutions is inconsistent with other documentation

which was filed against the emacs package, has been closed.

The explanation is attached below, along with your original report.
If you require more details, please reply to 50903 <at> debbugs.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: 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.

[Message part 3 (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 4 (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)]

Previous Next

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