From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.help Subject: Re: No return value in doc string Date: Wed, 26 Apr 2006 20:34:07 +0300 Message-ID: References: <87y7xv3jja.fsf@hans.local.net> NNTP-Posting-Host: main.gmane.org X-Trace: sea.gmane.org 1146073086 23341 80.91.229.2 (26 Apr 2006 17:38:06 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Wed, 26 Apr 2006 17:38:06 +0000 (UTC) Original-X-From: help-gnu-emacs-bounces+geh-help-gnu-emacs=m.gmane.org@gnu.org Wed Apr 26 19:38:01 2006 Return-path: Envelope-to: geh-help-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([199.232.76.165]) by ciao.gmane.org with esmtp (Exim 4.43) id 1FYnxe-0008Dn-Ni for geh-help-gnu-emacs@m.gmane.org; Wed, 26 Apr 2006 19:37:59 +0200 Original-Received: from localhost ([127.0.0.1] helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1FYnxe-0005LC-5a for geh-help-gnu-emacs@m.gmane.org; Wed, 26 Apr 2006 13:37:58 -0400 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1FYnxU-0005IE-By for help-gnu-emacs@gnu.org; Wed, 26 Apr 2006 13:37:48 -0400 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1FYnxR-0005EO-FS for help-gnu-emacs@gnu.org; Wed, 26 Apr 2006 13:37:47 -0400 Original-Received: from [199.232.76.173] (helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1FYnxR-0005Dw-9m for help-gnu-emacs@gnu.org; Wed, 26 Apr 2006 13:37:45 -0400 Original-Received: from [192.114.186.20] (helo=nitzan.inter.net.il) by monty-python.gnu.org with esmtp (Exim 4.52) id 1FYo0A-0001iG-JB for help-gnu-emacs@gnu.org; Wed, 26 Apr 2006 13:40:34 -0400 Original-Received: from HOME-C4E4A596F7 (IGLD-80-230-14-110.inter.net.il [80.230.14.110]) by nitzan.inter.net.il (MOS 3.7.3-GA) with ESMTP id DFI27374 (AUTH halo1); Wed, 26 Apr 2006 20:34:01 +0300 (IDT) Original-To: help-gnu-emacs@gnu.org In-reply-to: <87y7xv3jja.fsf@hans.local.net> (message from Dieter Wilhelm on Mon, 24 Apr 2006 02:27:05 +0200) X-BeenThere: help-gnu-emacs@gnu.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: Users list for the GNU Emacs text editor List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Original-Sender: help-gnu-emacs-bounces+geh-help-gnu-emacs=m.gmane.org@gnu.org Errors-To: help-gnu-emacs-bounces+geh-help-gnu-emacs=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.help:34674 Archived-At: > From: Dieter Wilhelm > Date: Mon, 24 Apr 2006 02:27:05 +0200 > > Is there any policy for the documentation string of the return value? I don't know if there is a policy, but I think return values should be documented. > The Elisp programming guidelines just mention that the documentation > string for functions should answer the question "What does this > function do?". That includes what value it returns, IMHO. > So I'd consider leaving out the return value in a doc > string of an interactive function a failure (please have a look at > `next-line' `previous-line' and `make-frame'). What version of Emacs do you have? In the current development sources, the doc string of make-frame already says: Return a newly created frame displaying the current buffer. So the return value, which is the frame object, is already documented. As for the other two, the return nil, i.e. nothing, so I think it's okay to say nothing about the (absent) return value. That said,... > Should I report this as bugs or is this a bit over the top? ...feel free to report if you disagree with my reasoning.