GNU bug report logs - #1351
23.0.60; Provide doc strings for functions in 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 1351 in the body.
You can then email your comments to 1351 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> emacsbugs.donarmstrong.com (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: <emacs-pretest-bug <at> gnu.org>
Subject: 23.0.60; Provide doc strings for functions in replace.el
Date: Sat, 15 Nov 2008 11:20:04 -0800

Please provide a doc string for these functions. At the very least,
provide a comment for each explaining what it does and what its
arguments are.
 
query-replace-descr
query-replace-read-args
occur-mode-find-occurrence
occur-find-match
occur-accumulate-lines
occur-read-primary-args
occur-1
occur-engine-add-prefix
occur-engine
occur-context-lines (has a comment)
replace-eval-replacement
replace-loop-through-replacements (has a comment)
replace-highlight
replace-dehighlight
 

Likewise, for these variables:
 
query-replace-history
replace-overlay
 
 
 
In GNU Emacs 23.0.60.1 (i386-mingw-nt5.1.2600)
 of 2008-11-08 on LENNART-69DE564
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (3.4) --no-opt --cflags -Ic:/g/include
-fno-crossjumping'
 

Message #8 received at 1351 <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Glenn Morris <rgm <at> gnu.org>
To: 1351 <at> debbugs.gnu.org
Subject: Re: bug#1351: 23.0.60; Provide doc strings for functions in replace.el
Date: Sat, 15 Nov 2008 17:58:27 -0500

Drew Adams wrote (on Sat, 15 Nov 2008 at 11:20 -0800):

> Please provide a doc string for these functions. At the very least,
> provide a comment for each explaining what it does and what its
> arguments are.

In other words, a doc string.

> query-replace-descr

Yes, many functions in Emacs unfortunately lack doc strings. It is not
very difficult to find them. Let me save you the trouble of opening
bugs for them all:

(let (undocumented)
  (mapatoms (lambda (s)
              (and (fboundp s)
                   (not (documentation s))
                   (push s undocumented))))
  undocumented))

Would you like to write some?

Message #13 received at 1351 <at> emacsbugs.donarmstrong.com (full text, mbox):

From: "Juanma Barranquero" <lekktu <at> gmail.com>
To: "Glenn Morris" <rgm <at> gnu.org>
Cc: 1351 <at> debbugs.gnu.org
Subject: Re: bug#1351: 23.0.60; Provide doc strings for functions in replace.el
Date: Sun, 16 Nov 2008 00:27:08 +0100

On Sat, Nov 15, 2008 at 23:58, Glenn Morris <rgm <at> gnu.org> wrote:

> (let (undocumented)
>  (mapatoms (lambda (s)
>              (and (fboundp s)
>                   (not (documentation s))
>                   (push s undocumented))))
>  undocumented))

Had you tried it (removing the last ")"), you would've caught an unrelated bug:

 => *** Eval error ***  Symbol's function definition is void:
c-put-char-property-fun

In cc-defs.el, `c-put-char-property-fun' is aliased to the output of
an expression that is nil on current Emacs.

C-h f c-put-char-property-fun <ENTER>

c-put-char-property-fun is an alias for `nil',
which is not defined.  Please make a bug report.

  Juanma

Message #16 received at 1351 <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Glenn Morris <rgm <at> gnu.org>
To: "Juanma Barranquero" <lekktu <at> gmail.com>
Cc: 1351 <at> debbugs.gnu.org
Subject: Re: bug#1351: 23.0.60; Provide doc strings for functions in replace.el
Date: Sat, 15 Nov 2008 18:43:53 -0500

clone 1351 -1
retitle -1 c-put-char-property-fun alias problem
reassign -1 emacs,cc-mode
stop

"Juanma Barranquero" wrote:

> Had you tried it (removing the last ")"), you would've caught an
> unrelated bug:

ITYM "when you tried it, if you happened to have cc-defs loaded".

Similarly, had I tried it in emacs -Q, I would have seen a similar
problem with advertised-widget-backward.

Message #23 received at 1351 <at> emacsbugs.donarmstrong.com (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: "'Glenn Morris'" <rgm <at> gnu.org>, <1351 <at> debbugs.gnu.org>
Subject: RE: bug#1351: 23.0.60; Provide doc strings for functions in replace.el
Date: Sat, 15 Nov 2008 16:06:21 -0800

> From: Glenn Morris Sent: Saturday, November 15, 2008 2:58 PM
> Yes, many functions in Emacs unfortunately lack doc strings. It is not
> very difficult to find them. Let me save you the trouble of opening
> bugs for them all:
> (let (undocumented)
>   (mapatoms (lambda (s)
>               (and (fboundp s)
>                    (not (documentation s))
>                    (push s undocumented))))
>   undocumented))

Impertinent and not helpful. I'm not looking for them all. This is not a report
that all functions and variables need doc strings.

The functions and variables I reported, in particular, could use doc strings.
That would help at least one user, me, understand the code.

> Would you like to write some?

No.

When I understand code that lacks doc strings where doc strings would help, I
don't hesitate to send proposed doc along. Likewise, for doc-string corrections.
When I don't understand code that lacks doc strings, I report that they could
help understanding.

Would you like to write some? If not, pass. Let me save you the trouble of
responding uselessly to bug reports - feel free not to bother.

Message #28 received at submit <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>, 1351 <at> debbugs.gnu.org
Cc: rgm <at> gnu.org, bug-gnu-emacs <at> gnu.org
Subject: Re: bug#1351: 23.0.60; Provide doc strings for functions in replace.el
Date: Sun, 16 Nov 2008 06:19:50 +0200

> From: "Drew Adams" <drew.adams <at> oracle.com>
> Date: Sat, 15 Nov 2008 16:06:21 -0800
> Cc: 
> 
> Would you like to write some? If not, pass. Let me save you the trouble of
> responding uselessly to bug reports - feel free not to bother.

That was unnecessarily harsh, Drew.  There was nothing wrong with what
Glenn wrote, neither in form, nor in essence.  Pouncing on him for
that is not fair at all, given the amount of work he invests in
maintaining Emacs in general, and diagnosing and fixing bugs in
particular.

Perhaps you were having a bad day.  We all do from time to time.

Message #38 received at submit <at> emacsbugs.donarmstrong.com (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: "'Eli Zaretskii'" <eliz <at> gnu.org>, <1351 <at> debbugs.gnu.org>
Cc: <rgm <at> gnu.org>, <bug-gnu-emacs <at> gnu.org>
Subject: RE: bug#1351: 23.0.60; Provide doc strings for functions in replace.el
Date: Sun, 16 Nov 2008 00:05:43 -0800

> > Would you like to write some? If not, pass. Let me save you 
> > the trouble of responding uselessly to bug reports - feel
> > free not to bother.
> 
> That was unnecessarily harsh, Drew.  There was nothing wrong with what
> Glenn wrote, neither in form, nor in essence.  Pouncing on him for
> that is not fair at all, given the amount of work he invests in
> maintaining Emacs in general, and diagnosing and fixing bugs in
> particular.
> 
> Perhaps you were having a bad day.  We all do from time to time.

Funny. I feel exactly that way about Glenn's message. It was uncalled for:
unnecessary, unhelpful, irrelevant, and impertinent. Perhaps he was having a bad
day.

Wrt my language, which you quoted: I simply echoed his language.

As to the substance - the rest of my reply, I simply explained why I sent that
particular bug report, even though no such explanation should be necessary.

There was no need to reply to the report as Glenn did. His reply did not advance
anything; it was merely sarcasm and provocation.

If it's not helpful to send doc-string bug reports then I'll take Glenn's advice
and save myself the trouble. In that case, his message to not bother will have
served some purpose.

Message #48 received at submit <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 1351 <at> debbugs.gnu.org, rgm <at> gnu.org, bug-gnu-emacs <at> gnu.org
Subject: Re: bug#1351: 23.0.60; Provide doc strings for functions in replace.el
Date: Sun, 16 Nov 2008 23:58:30 +0200

> From: "Drew Adams" <drew.adams <at> oracle.com>
> Cc: <rgm <at> gnu.org>, <bug-gnu-emacs <at> gnu.org>
> Date: Sun, 16 Nov 2008 00:05:43 -0800
> 
> His reply did not advance anything; it was merely sarcasm and
> provocation.

FWIW, I see neither in what he wrote.  Perhaps you should ask for a
second opinion.

Message #58 received at submit <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 1351 <at> debbugs.gnu.org, Drew Adams <drew.adams <at> oracle.com>,
        bug-gnu-emacs <at> gnu.org
Subject: Re: bug#1351: 23.0.60; Provide doc strings for functions in replace.el
Date: Sun, 16 Nov 2008 18:13:50 -0500

>> His reply did not advance anything; it was merely sarcasm and
>> provocation.
> FWIW, I see neither in what he wrote.  Perhaps you should ask for a
> second opinion.

Let's just say that neither was best-form, and neither was nasty.
And they both win.  We all have bad days, but we all want to move
forward, so let's concentrate on that and try and ignore slips.
Thank you,


        Stefan

View this message in rfc822 format

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: "Drew Adams" <drew.adams <at> oracle.com>
Cc: 1351 <at> debbugs.gnu.org
Subject: bug#1351: 23.0.60; Provide doc strings for functions in replace.el
Date: Sun, 09 Feb 2014 19:38:21 -0800

"Drew Adams" <drew.adams <at> oracle.com> writes:

> Please provide a doc string for these functions. At the very least,
> provide a comment for each explaining what it does and what its
> arguments are.
>
> query-replace-descr
> query-replace-read-args
> occur-mode-find-occurrence
> occur-find-match
> occur-accumulate-lines
> occur-read-primary-args
> occur-1
> occur-engine-add-prefix
> occur-engine
> occur-context-lines (has a comment)
> replace-eval-replacement
> replace-loop-through-replacements (has a comment)
> replace-highlight
> replace-dehighlight

They're internal functions.  Closing.

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/

Previous Next

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