GNU bug report logs - #31207
26; Doc strings of commands and other functions of `replace.el'

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#31207: closed (26; Doc strings of commands and other
 functions of `replace.el')
Date: Wed, 09 Oct 2019 10:16:02 +0000

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

Your message dated Wed, 09 Oct 2019 13:14:41 +0300
with message-id <831rvmw7hq.fsf <at> gnu.org>
and subject line Re: bug#31207: 26; Doc strings of commands and other functions of `replace.el'
has caused the debbugs.gnu.org bug report #31207,
regarding 26; Doc strings of commands and other functions of `replace.el'
to be marked as done.

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


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

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

From: Drew Adams <drew.adams <at> oracle.com>
To: bug-gnu-emacs <at> gnu.org
Subject: 26; Doc strings of commands and other functions of `replace.el'
Date: Wed, 18 Apr 2018 08:28:51 -0700 (PDT)

1. The doc strings of many functions do not describe all of their args,
including these:

 query-replace-read-from
 query-replace-compile-replacement
 query-replace-read-to
 query-replace
 query-replace-regexp
 replace-string
 replace-regexp
 occur-mode-goto-occurrence
 occur-next-error
 occur-rename-buffer
 multi-occur
 multi-occur-in-matching-buffers
 perform-replace
 
In many cases, it is the more recently added args which are not
documented (of the args of recently added functions).  This suggests
oversight/laziness - no one has yet bothered to DTRT for those newly
added args.

2. There are also numerous functions in this file that have no doc
strings.  They should have doc strings, and those doc strings should
describe the arguments.  For example, none of the `occur-engine'
functions have doc strings.  Laziness on the part of the person who
added them, perhaps - but this should be corrected now.

3. In some cases there are poorly named args whose names are not
explained (the args are not really described).  For example, BUFREGEXP.




In GNU Emacs 26.1 (build 1, x86_64-w64-mingw32)
 of 2018-04-10
Repository revision: c267421647510319d2a70554e42f0d1c394dba0a
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --without-dbus --host=x86_64-w64-mingw32
 --without-compress-install 'CFLAGS=-O2 -static -g3''

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: rpluim <at> gmail.com, 31207-done <at> debbugs.gnu.org
Subject: Re: bug#31207: 26;
 Doc strings of commands and other functions of `replace.el'
Date: Wed, 09 Oct 2019 13:14:41 +0300

> Date: Tue, 8 Oct 2019 07:37:18 -0700 (PDT)
> From: Drew Adams <drew.adams <at> oracle.com>
> Cc: 31207 <at> debbugs.gnu.org
> 
> >     Drew> If you feel that this bug is completely fixed in
> >     Drew> Emacs 27, please close it as "fixed".  Thx.
> > 
> > I canʼt answer that, because I donʼt know which of the defuns in
> > replace.el you feel are underdocumented. Please donʼt say 'all of
> > them'.
> 
> Any doc string that does not describe all of
> the function arguments, either directly or
> indirectly (by referencing another doc string).
> 
> This is nothing new.  Function doc strings
> should describe the arguments.  That's all.

What an unhelpful response.  Do you realize how such responses shoot
yourself (and us) in the foot by preventing well-meaning contributors
from fixing your bug reports?

I fixed the doc strings in all functions except perform-replace.  The
latter is clearly an internal function, and its doc string says so.

Previous Next

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