From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: "Juanma Barranquero" Newsgroups: gmane.emacs.devel Subject: docstring of `kill-buffer' Date: Sat, 16 Dec 2006 01:17:28 +0100 Message-ID: NNTP-Posting-Host: dough.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=UTF-8; format=flowed Content-Transfer-Encoding: 7bit X-Trace: sea.gmane.org 1166228270 29653 80.91.229.10 (16 Dec 2006 00:17:50 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Sat, 16 Dec 2006 00:17:50 +0000 (UTC) Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sat Dec 16 01:17:49 2006 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([199.232.76.165]) by dough.gmane.org with esmtp (Exim 4.50) id 1GvNFK-0006Qo-Fw for ged-emacs-devel@m.gmane.org; Sat, 16 Dec 2006 01:17:46 +0100 Original-Received: from localhost ([127.0.0.1] helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1GvNFJ-0005DN-TN for ged-emacs-devel@m.gmane.org; Fri, 15 Dec 2006 19:17:45 -0500 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1GvNF4-0005D4-OW for emacs-devel@gnu.org; Fri, 15 Dec 2006 19:17:30 -0500 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1GvNF4-0005Cj-9j for emacs-devel@gnu.org; Fri, 15 Dec 2006 19:17:30 -0500 Original-Received: from [199.232.76.173] (helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1GvNF4-0005Cf-3U for emacs-devel@gnu.org; Fri, 15 Dec 2006 19:17:30 -0500 Original-Received: from [66.249.92.172] (helo=ug-out-1314.google.com) by monty-python.gnu.org with esmtp (Exim 4.52) id 1GvNF3-0008CZ-W5 for emacs-devel@gnu.org; Fri, 15 Dec 2006 19:17:30 -0500 Original-Received: by ug-out-1314.google.com with SMTP id j3so1160178ugf for ; Fri, 15 Dec 2006 16:17:29 -0800 (PST) DomainKey-Signature: a=rsa-sha1; q=dns; c=nofws; s=beta; d=gmail.com; h=received:message-id:date:from:to:subject:mime-version:content-type:content-transfer-encoding:content-disposition; b=BXWbxTDzgWiLmex3lBJHKdxr530KAcM2L/xniMFPnVEfiHz2FX3y8nV5WqYDs27BbUELRZ8GOt6wx28rc7NT4D8Bnpy7YYmjm30ax+eP199LfShfA6bZHIfKnDef/TWKo4kwiXokgqOegFZCaWfdkpohoLXZc4rKJi5UaxH4u7U= Original-Received: by 10.82.105.13 with SMTP id d13mr136502buc.1166228248727; Fri, 15 Dec 2006 16:17:28 -0800 (PST) Original-Received: by 10.82.147.2 with HTTP; Fri, 15 Dec 2006 16:17:28 -0800 (PST) Original-To: "Emacs Devel" Content-Disposition: inline X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.devel:63812 Archived-At: I have a few problems with the current docstring of `kill-buffer': - It says that it returns t if the buffer is killed, and "nil if user says no". It would be more accurate to simply say "nil if it is not killed"; it's not always the user who stops the killing (for example, I use Noah S. Friedman's protbuf.el). - It does not mention `kill-buffer-query-functions', which is yet more puzzling after the previous paragraph. - The description of `kill-buffer-hook' is too verbose, and insists on saying that it "may be local to that buffer"; but `kill-buffer-hook' is not different from any other normal hook. I propose the following change, which also clarifies a bit `kill-buffer-query-functions'. /L/e/k/t/u Index: src/buffer.c =================================================================== RCS file: /cvsroot/emacs/emacs/src/buffer.c,v retrieving revision 1.516 diff -u -2 -r1.516 buffer.c --- src/buffer.c 11 Dec 2006 15:41:07 -0000 1.516 +++ src/buffer.c 11 Dec 2006 17:04:22 -0000 @@ -1332,13 +1332,14 @@ DEFUN ("kill-buffer", Fkill_buffer, Skill_buffer, 1, 1, "bKill buffer: ", doc: /* Kill the buffer BUFFER. -The argument may be a buffer or may be the name of a buffer. -An argument of nil means kill the current buffer. +The argument may be a buffer or the name of a buffer. +With a nil argument, kill the current buffer. -Value is t if the buffer is actually killed, nil if user says no. +Value is t if the buffer is actually killed, nil otherwise. -The value of `kill-buffer-hook' (which may be local to that buffer), -if not void, is a list of functions to be called, with no arguments, -before the buffer is actually killed. The buffer to be killed is current -when the hook functions are called. +The functions in `kill-buffer-query-functions' are called with BUFFER as +the current buffer. If any of them returns nil, the buffer is not killed. + +The hook `kill-buffer-hook' is run before the buffer is actually killed. +The buffer being killed will be current while the hook is running. Any processes that have this buffer as the `process-buffer' are killed @@ -6045,5 +6046,7 @@ DEFVAR_LISP ("kill-buffer-query-functions", &Vkill_buffer_query_functions, - doc: /* List of functions called with no args to query before killing a buffer. */); + doc: /* List of functions called with no args to query before killing a buffer. +The buffer being killed will be current while the functions are running. +If any of them returns nil, the buffer is not killed. */); Vkill_buffer_query_functions = Qnil;