bug#31207: 26; Doc strings of commands and other functions of `replace.el'

bug#31207: 26; Doc strings of commands and other functions of `replace.el'

[Drew Adams]

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''

bug#31207: 26; Doc strings of commands and other functions of `replace.el'

[Drew Adams]

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).

bug#31207: 26; Doc strings of commands and other functions of `replace.el'

[Robert Pluim]

>>>>> On Sun, 6 Oct 2019 10:27:23 -0700 (PDT), Drew Adams <drew.adams@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

bug#31207: 26; Doc strings of commands and other functions of `replace.el'

[Drew Adams]

>     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.

bug#31207: 26; Doc strings of commands and other functions of `replace.el'

[Robert Pluim]

>>>>> On Mon, 7 Oct 2019 10:29:15 -0700 (PDT), Drew Adams <drew.adams@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

bug#31207: 26; Doc strings of commands and other functions of `replace.el'

[Drew Adams]

>     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.

bug#31207: 26; Doc strings of commands and other functions of `replace.el'

[Eli Zaretskii]

> Date: Tue, 8 Oct 2019 07:37:18 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 31207@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.