From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: "Drew Adams" Newsgroups: gmane.emacs.bugs Subject: bug#286: 23.0.60; doc string for yank-pop Date: Thu, 22 May 2008 10:41:24 -0700 Message-ID: <00af01c8bc33$0eb499d0$c2b22382@us.oracle.com> References: <87abii2qrp.fsf@stupidchicken.com> Reply-To: Drew Adams , 286@emacsbugs.donarmstrong.com NNTP-Posting-Host: lo.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit X-Trace: ger.gmane.org 1211478919 8724 80.91.229.12 (22 May 2008 17:55:19 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Thu, 22 May 2008 17:55:19 +0000 (UTC) Cc: 286@emacsbugs.donarmstrong.com To: "'Chong Yidong'" Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Thu May 22 19:55:53 2008 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([199.232.76.165]) by lo.gmane.org with esmtp (Exim 4.50) id 1JzEyY-0005wP-Jz for geb-bug-gnu-emacs@m.gmane.org; Thu, 22 May 2008 19:53:14 +0200 Original-Received: from localhost ([127.0.0.1]:52022 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1JzExo-00031Y-60 for geb-bug-gnu-emacs@m.gmane.org; Thu, 22 May 2008 13:52:28 -0400 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1JzExC-0002k2-Vp for bug-gnu-emacs@gnu.org; Thu, 22 May 2008 13:51:51 -0400 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1JzEx9-0002hy-Nv for bug-gnu-emacs@gnu.org; Thu, 22 May 2008 13:51:49 -0400 Original-Received: from [199.232.76.173] (port=37498 helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1JzEx9-0002hp-BH for bug-gnu-emacs@gnu.org; Thu, 22 May 2008 13:51:47 -0400 Original-Received: from rzlab.ucr.edu ([138.23.92.77]:52467) by monty-python.gnu.org with esmtps (TLS-1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.60) (envelope-from ) id 1JzEx8-0003hV-HG for bug-gnu-emacs@gnu.org; Thu, 22 May 2008 13:51:46 -0400 Original-Received: from rzlab.ucr.edu (rzlab.ucr.edu [127.0.0.1]) by rzlab.ucr.edu (8.13.8/8.13.8/Debian-3) with ESMTP id m4MHpgmh014162; Thu, 22 May 2008 10:51:43 -0700 Original-Received: (from debbugs@localhost) by rzlab.ucr.edu (8.13.8/8.13.8/Submit) id m4MHo4C6013146; Thu, 22 May 2008 10:50:04 -0700 X-Loop: don@donarmstrong.com Resent-From: "Drew Adams" Resent-To: bug-submit-list@donarmstrong.com Resent-CC: Emacs Bugs Resent-Date: Thu, 22 May 2008 17:50:04 +0000 Resent-Message-ID: Resent-Sender: don@donarmstrong.com X-Emacs-PR-Message: report 286 X-Emacs-PR-Package: emacs X-Emacs-PR-Keywords: Original-Received: via spool by 286-submit@emacsbugs.donarmstrong.com id=B286.121147814711788 (code B ref 286); Thu, 22 May 2008 17:50:04 +0000 Original-Received: (at 286) by emacsbugs.donarmstrong.com; 22 May 2008 17:42:27 +0000 Original-Received: from agminet01.oracle.com (agminet01.oracle.com [141.146.126.228]) by rzlab.ucr.edu (8.13.8/8.13.8/Debian-3) with ESMTP id m4MHgNQM011782 for <286@emacsbugs.donarmstrong.com>; Thu, 22 May 2008 10:42:24 -0700 Original-Received: from rgmgw1.us.oracle.com (rgmgw1.us.oracle.com [138.1.186.110]) by agminet01.oracle.com (Switch-3.2.4/Switch-3.1.7) with ESMTP id m4MHgGCP014644; Thu, 22 May 2008 12:42:16 -0500 Original-Received: from acsmt350.oracle.com (acsmt350.oracle.com [141.146.40.150]) by rgmgw1.us.oracle.com (Switch-3.2.4/Switch-3.2.4) with ESMTP id m4MF2K0e022577; Thu, 22 May 2008 11:42:16 -0600 Original-Received: from inet-141-146-46-1.oracle.com by acsmt350.oracle.com with ESMTP id 3679655961211478079; Thu, 22 May 2008 10:41:19 -0700 Original-Received: from dradamslap1 (/130.35.178.194) by bhmail.oracle.com (Oracle Beehive Gateway v4.0) with ESMTP ; Thu, 22 May 2008 10:41:18 -0700 X-Mailer: Microsoft Office Outlook 11 Thread-Index: Aci8MdtgbbaNZ4DGR6ytNUlZF5SlMAAAD5Hg X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.3198 In-Reply-To: <87abii2qrp.fsf@stupidchicken.com> X-Brightmail-Tracker: AAAAAQAAAAI= X-Brightmail-Tracker: AAAAAQAAAAI= X-Whitelist: TRUE X-Whitelist: TRUE X-detected-kernel: by monty-python.gnu.org: Linux 2.6 (newer, 3) Resent-Date: Thu, 22 May 2008 13:51:49 -0400 X-BeenThere: bug-gnu-emacs@gnu.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Original-Sender: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.bugs:18091 Archived-At: > 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.