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

[Emacs bug Tracking System]

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