bug-gnu-emacs
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

bug#286: marked as done (23.0.60; doc string for yank-pop)


From: Emacs bug Tracking System
Subject: bug#286: marked as done (23.0.60; doc string for yank-pop)
Date: Thu, 22 May 2008 11:30:03 -0700

Your message dated Thu, 22 May 2008 14:23:50 -0400
with message-id <address@hidden>
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 address@hidden
immediately.)


-- 
286: http://emacsbugs.donarmstrong.com/cgi-bin/bugreport.cgi?bug=286
Emacs Bug Tracking System
Contact address@hidden with problems
--- Begin Message --- Subject: 23.0.60; doc string for yank-pop Date: Tue, 20 May 2008 10:38:32 -0700
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'
 






--- End Message ---
--- Begin Message --- Subject: Re: bug#286: 23.0.60; doc string for yank-pop Date: Thu, 22 May 2008 14:23:50 -0400 User-agent: Gnus/5.13 (Gnus v5.13) Emacs/23.0.60 (gnu/linux)
>> > 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


--- End Message ---

reply via email to

[Prev in Thread] Current Thread [Next in Thread]