--- Begin Message ---
|
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''
--- End Message ---
--- Begin Message ---
|
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 <address@hidden>
> Cc: address@hidden
>
> > 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.
--- End Message ---