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

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

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


From: Drew Adams
Subject: bug#286: 23.0.60; doc string for yank-pop
Date: Thu, 22 May 2008 10:41:24 -0700

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







reply via email to

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