bug#1351: 23.0.60; Provide doc strings for functions in replace.el

bug#1351: 23.0.60; Provide doc strings for functions in replace.el

[Drew Adams]

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'
 

bug#1351: 23.0.60; Provide doc strings for functions in replace.el

[Glenn Morris]

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?

bug#1351: 23.0.60; Provide doc strings for functions in replace.el

[Juanma Barranquero]

On Sat, Nov 15, 2008 at 23:58, Glenn Morris <rgm@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

bug#1351: 23.0.60; Provide doc strings for functions in replace.el

[Glenn Morris]

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.

Processed: Re: bug#1351: 23.0.60; Provide doc strings for functions in replace.el

[Emacs bug Tracking System]

Processing commands for control@emacsbugs.donarmstrong.com:

> clone 1351 -1
bug#1351: 23.0.60; Provide doc strings for functions in replace.el
bug 1351 cloned as bug 1353.

> retitle -1 c-put-char-property-fun alias problem
bug#1353: 23.0.60; Provide doc strings for functions in replace.el
Changed bug title to `c-put-char-property-fun alias problem' from `23.0.60; Provide doc strings for functions in replace.el'.

> reassign -1 emacs,cc-mode
bug#1353: c-put-char-property-fun alias problem
Warning: Unknown package 'cc-mode'
bug reassigned from package `emacs' to `emacs,cc-mode'.

> stop
Stopping processing here.

Please contact me if you need assistance.

Don Armstrong
(administrator, Emacs bugs database)

bug#1351: 23.0.60; Provide doc strings for functions in replace.el

[Drew Adams]

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

bug#1351: 23.0.60; Provide doc strings for functions in replace.el

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@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.

bug#1351: 23.0.60; Provide doc strings for functions in replace.el

[Drew Adams]

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

bug#1351: 23.0.60; Provide doc strings for functions in replace.el

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Cc: <rgm@gnu.org>, <bug-gnu-emacs@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.

bug#1351: 23.0.60; Provide doc strings for functions in replace.el

[Stefan Monnier]

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

bug#1353: marked as done (c-put-char-property-fun alias problem)

[Emacs bug Tracking System]

[-- Attachment #1: Type: text/plain, Size: 863 bytes --]


Your message dated Mon, 17 Nov 2008 03:43:30 -0500
with message-id <18721.11954.779606.826706@fencepost.gnu.org>
and subject line Re: Bug#1353: c-put-char-property-fun alias problem
has caused the Emacs bug report #1353,
regarding c-put-char-property-fun alias problem
to be marked as done.

This means that you claim that the problem has been dealt with.
If this is not the case it is now your responsibility to reopen the
bug report if necessary, and/or fix the problem forthwith.

(NB: If you are a system administrator and have no idea what this
message is talking about, this may indicate a serious mail system
misconfiguration somewhere. Please contact don@donarmstrong.com
immediately.)


-- 
1353: http://emacsbugs.donarmstrong.com/cgi-bin/bugreport.cgi?bug=1353
Emacs Bug Tracking System
Contact don@donarmstrong.com with problems

[-- Attachment #2: Type: message/rfc822, Size: 3421 bytes --]

From: "Drew Adams" <drew.adams@oracle.com>
To: <emacs-pretest-bug@gnu.org>
Subject: 23.0.60; Provide doc strings for functions in replace.el
Date: Sat, 15 Nov 2008 11:20:04 -0800
Message-ID: <005a01c94757$29f2e1c0$0200a8c0@us.oracle.com>

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'
 




[-- Attachment #3: Type: message/rfc822, Size: 1432 bytes --]

From: Glenn Morris <rgm@gnu.org>
To: 1353-done@emacsbugs.donarmstrong.com
Subject: Re: Bug#1353: c-put-char-property-fun alias problem
Date: Mon, 17 Nov 2008 03:43:30 -0500
Message-ID: <18721.11954.779606.826706@fencepost.gnu.org>


2008-11-17  Glenn Morris  <rgm@gnu.org>

  * progmodes/cc-defs.el (c-put-char-property-fun): Add
  fallback definition of 'ignore, rather than nil.  (Bug#1353)

bug#1351: 23.0.60; Provide doc strings for functions in replace.el

[Lars Ingebrigtsen]

"Drew Adams" <drew.adams@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/