GNU bug report logs -
#31207
26; Doc strings of commands and other functions of `replace.el'
Previous Next
To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 31207 in the body.
You can then email your comments to 31207 AT debbugs.gnu.org in the normal way.
Toggle the display of automated, internal messages from the tracker.
Report forwarded
to
bug-gnu-emacs <at> gnu.org
:
bug#31207
; Package
emacs
.
(Wed, 18 Apr 2018 15:30:03 GMT)
Full text and
rfc822 format available.
Acknowledgement sent
to
Drew Adams <drew.adams <at> oracle.com>
:
New bug report received and forwarded. Copy sent to
bug-gnu-emacs <at> gnu.org
.
(Wed, 18 Apr 2018 15:30:04 GMT)
Full text and
rfc822 format available.
Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):
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''
Information forwarded
to
bug-gnu-emacs <at> gnu.org
:
bug#31207
; Package
emacs
.
(Sun, 06 Oct 2019 17:28:01 GMT)
Full text and
rfc822 format available.
Message #8 received at 31207 <at> debbugs.gnu.org (full text, mbox):
Ping.
I was about to file a new bug, just to say that for
`query-replace(-regexp)' there is no description of
argument REGION-NONCONTIGUOUS-P.
Checked my posted bug reports and came across this
one, which never got a reply.
The functions in `replace.el' really need to have
their arguments described in their doc strings.
Especially so, since most of the functions are not
documented in the Elisp manual. The doc strings
are all users have as guidance (beyond the source
code itself).
Information forwarded
to
bug-gnu-emacs <at> gnu.org
:
bug#31207
; Package
emacs
.
(Mon, 07 Oct 2019 11:37:02 GMT)
Full text and
rfc822 format available.
Message #11 received at 31207 <at> debbugs.gnu.org (full text, mbox):
>>>>> On Sun, 6 Oct 2019 10:27:23 -0700 (PDT), Drew Adams <drew.adams <at> oracle.com> said:
Drew> Ping.
Drew> I was about to file a new bug, just to say that for
Drew> `query-replace(-regexp)' there is no description of
Drew> argument REGION-NONCONTIGUOUS-P.
query-replace:
Arguments FROM-STRING, TO-STRING, DELIMITED, START, END, BACKWARD, and
REGION-NONCONTIGUOUS-P are passed to `perform-replace' (which see).
perform-replace:
Non-nil REGION-NONCONTIGUOUS-P means that the region is composed of
noncontiguous pieces. The most common example of this is a
rectangular region, where the pieces are separated by newline
characters."
Drew> Checked my posted bug reports and came across this
Drew> one, which never got a reply.
Drew> The functions in `replace.el' really need to have
Drew> their arguments described in their doc strings.
Did you have specific functions in mind? There are quite a few in that
file.
Robert
Information forwarded
to
bug-gnu-emacs <at> gnu.org
:
bug#31207
; Package
emacs
.
(Mon, 07 Oct 2019 17:31:02 GMT)
Full text and
rfc822 format available.
Message #14 received at 31207 <at> debbugs.gnu.org (full text, mbox):
> Drew> for `query-replace(-regexp)' there is no
> description of argument REGION-NONCONTIGUOUS-P.
>
> query-replace:
>
> Arguments FROM-STRING, TO-STRING, DELIMITED, START, END, BACKWARD, and
> REGION-NONCONTIGUOUS-P are passed to `perform-replace' (which see).
I have only Emacs 26.3 - the latest release, and the
release I reported on. That text is not in the doc string.
> perform-replace:
>
> Non-nil REGION-NONCONTIGUOUS-P means that the region is composed of
> noncontiguous pieces. The most common example of this is a
> rectangular region, where the pieces are separated by newline
> characters."
That too is missing from Emacs 26.3.
If you feel that this bug is completely fixed in
Emacs 27, please close it as "fixed". Thx.
Information forwarded
to
bug-gnu-emacs <at> gnu.org
:
bug#31207
; Package
emacs
.
(Tue, 08 Oct 2019 11:33:01 GMT)
Full text and
rfc822 format available.
Message #17 received at 31207 <at> debbugs.gnu.org (full text, mbox):
>>>>> On Mon, 7 Oct 2019 10:29:15 -0700 (PDT), Drew Adams <drew.adams <at> oracle.com> said:
Drew> for `query-replace(-regexp)' there is no
>> description of argument REGION-NONCONTIGUOUS-P.
>>
>> query-replace:
>>
>> Arguments FROM-STRING, TO-STRING, DELIMITED, START, END, BACKWARD, and
>> REGION-NONCONTIGUOUS-P are passed to `perform-replace' (which see).
Drew> I have only Emacs 26.3 - the latest release, and the
Drew> release I reported on. That text is not in the doc string.
OK
>> perform-replace:
>>
>> Non-nil REGION-NONCONTIGUOUS-P means that the region is composed of
>> noncontiguous pieces. The most common example of this is a
>> rectangular region, where the pieces are separated by newline
>> characters."
Drew> That too is missing from Emacs 26.3.
OK
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'.
Rober
Information forwarded
to
bug-gnu-emacs <at> gnu.org
:
bug#31207
; Package
emacs
.
(Tue, 08 Oct 2019 14:38:01 GMT)
Full text and
rfc822 format available.
Message #20 received at 31207 <at> debbugs.gnu.org (full text, mbox):
> 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.
Reply sent
to
Eli Zaretskii <eliz <at> gnu.org>
:
You have taken responsibility.
(Wed, 09 Oct 2019 10:16:02 GMT)
Full text and
rfc822 format available.
Notification sent
to
Drew Adams <drew.adams <at> oracle.com>
:
bug acknowledged by developer.
(Wed, 09 Oct 2019 10:16:02 GMT)
Full text and
rfc822 format available.
Message #25 received at 31207-done <at> debbugs.gnu.org (full text, mbox):
> 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.
bug archived.
Request was from
Debbugs Internal Request <help-debbugs <at> gnu.org>
to
internal_control <at> debbugs.gnu.org
.
(Wed, 06 Nov 2019 12:24:05 GMT)
Full text and
rfc822 format available.
This bug report was last modified 4 years and 171 days ago.
Previous Next
GNU bug tracking system
Copyright (C) 1999 Darren O. Benham,
1997,2003 nCipher Corporation Ltd,
1994-97 Ian Jackson.