23.0.60; doc string for yank-pop

23.0.60; doc string for yank-pop

[Drew Adams]

The doc string includes this:
 
 "When this command inserts killed text into the buffer, it honors
 `yank-excluded-properties' and `yank-handler' as described in the
 doc string for `insert-for-yank-1', which see."
 
This is the doc string for a user command. It should not tell users to
refer to the doc string of an internal function (`insert-for-yank-1').
 
And "When this command inserts killed text into the buffer" seems
redundant - that is what this command _always_ does, no?
 

In GNU Emacs 23.0.60.1 (i386-mingw-nt5.1.2600)
 of 2008-05-04 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#286: marked as done (23.0.60; doc string for yank-pop)

[Emacs bug Tracking System]

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


Your message dated Thu, 22 May 2008 14:23:50 -0400
with message-id <jwv1w3uxksd.fsf-monnier+emacsbugreports@gnu.org>
and subject line Re: bug#286: 23.0.60; doc string for yank-pop
has caused the Emacs bug report #286,
regarding 23.0.60; doc string for yank-pop
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.)


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

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

From: "Drew Adams" <drew.adams@oracle.com>
To: <emacs-pretest-bug@gnu.org>
Cc: 
Subject: 23.0.60; doc string for yank-pop
Date: Tue, 20 May 2008 10:38:32 -0700
Message-ID: <000401c8baa0$5313cf40$0200a8c0@us.oracle.com>

The doc string includes this:
 
 "When this command inserts killed text into the buffer, it honors
 `yank-excluded-properties' and `yank-handler' as described in the
 doc string for `insert-for-yank-1', which see."
 
This is the doc string for a user command. It should not tell users to
refer to the doc string of an internal function (`insert-for-yank-1').
 
And "When this command inserts killed text into the buffer" seems
redundant - that is what this command _always_ does, no?
 

In GNU Emacs 23.0.60.1 (i386-mingw-nt5.1.2600)
 of 2008-05-04 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: 3053 bytes --]

From: Stefan Monnier <monnier@IRO.UMontreal.CA>
To: Drew Adams <drew.adams@ORACLE.COM>
Cc: 286-close@emacsbugs.donarmstrong.com, "'Chong Yidong'" <cyd@stupidchicken.com>
Subject: Re: bug#286: 23.0.60; doc string for yank-pop
Date: Thu, 22 May 2008 14:23:50 -0400
Message-ID: <jwv1w3uxksd.fsf-monnier+emacsbugreports@gnu.org>

>> > The doc string includes this:
>> > 
>> >  "When this command inserts killed text into the buffer, it honors
>> >  `yank-excluded-properties' and `yank-handler' as described in the
>> >  doc string for `insert-for-yank-1', which see."
>> > 
>> > This is the doc string for a user command. It should not 
>> > tell users to refer to the doc string of an internal function 
>> > (`insert-for-yank-1').
>> 
>> The text you quoted is primarily a note for programmers.  I 
>> don't think it violates any convention.

> Huh? It is a _doc string_, not a code comment. Doc strings are _not_
> just notes for programmers; they are documentation for _users_.

The difference between the two is not that large.

> It appears that when a change was made to the code that introduced
> `insert-for-yank-1' and the new behavior that "honors
> `yank-excluded-properties' and `yank-handler'", someone was lazy and
> just referred to the doc string for `insert-for-yank-1'. IOW, when
> code was moved to a new helper function, the doc string went with it,
> so the new doc string simply took the shortcut of referring to the doc
> string of the helper function.

Copying the text elsewhere will lead to bugs down the line when one of
the two copies doesn't get updated.
I think the current text is fine.  The only downside is that the user
has to click one more time to get at the details; that's very minor.


        Stefan