bug#286: 23.0.60; doc string for yank-pop

bug#286: 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: 23.0.60; doc string for yank-pop

[Chong Yidong]

Tags: wontfix

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

bug#286: 23.0.60; doc string for yank-pop

[Drew Adams]

> From: Chong Yidong Sent: Thursday, May 22, 2008 10:27 AM
> Tags: wontfix
> 
> > 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_.

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.

This laziness is not helpful to users. Please correct this. Put the user
information back in the doc string of the main function.