From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Dieter Wilhelm Newsgroups: gmane.emacs.help Subject: Re: No return value in doc string Date: Thu, 27 Apr 2006 03:16:37 +0200 Message-ID: <87ejzj3jii.fsf@hans.local.net> References: <87y7xv3jja.fsf@hans.local.net> NNTP-Posting-Host: main.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Trace: sea.gmane.org 1146157159 10737 80.91.229.2 (27 Apr 2006 16:59:19 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Thu, 27 Apr 2006 16:59:19 +0000 (UTC) Original-X-From: help-gnu-emacs-bounces+geh-help-gnu-emacs=m.gmane.org@gnu.org Thu Apr 27 18:59:14 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 1FZ9pT-0003lR-Ct for geh-help-gnu-emacs@m.gmane.org; Thu, 27 Apr 2006 18:59:00 +0200 Original-Received: from localhost ([127.0.0.1] helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1FZ9pS-0008US-V0 for geh-help-gnu-emacs@m.gmane.org; Thu, 27 Apr 2006 12:58:58 -0400 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1FZ4JJ-00022o-EV for help-gnu-emacs@gnu.org; Thu, 27 Apr 2006 07:05:25 -0400 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1FZ4JG-00022Y-6c for help-gnu-emacs@gnu.org; Thu, 27 Apr 2006 07:05:24 -0400 Original-Received: from [199.232.76.173] (helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1FZ4JG-00022O-2o for help-gnu-emacs@gnu.org; Thu, 27 Apr 2006 07:05:22 -0400 Original-Received: from [212.227.126.177] (helo=moutng.kundenserver.de) by monty-python.gnu.org with esmtp (Exim 4.52) id 1FZ4M7-0007ZU-Dv for help-gnu-emacs@gnu.org; Thu, 27 Apr 2006 07:08:21 -0400 Original-Received: from [84.167.57.21] (helo=duenenhof-wilhelm.de) by mrelayeu.kundenserver.de (node=mrelayeu3) with ESMTP (Nemesis), id 0MKxQS-1FZ4J940TH-0006sr; Thu, 27 Apr 2006 13:05:16 +0200 Original-Received: by duenenhof-wilhelm.de (Postfix, from userid 1000) id 5950D72243; Thu, 27 Apr 2006 03:16:37 +0200 (CEST) Original-To: help-gnu-emacs@gnu.org In-Reply-To: (Eli Zaretskii's message of "Wed, 26 Apr 2006 20:34:07 +0300") User-Agent: Gnus/5.11 (Gnus v5.11) Emacs/22.0.50 (gnu/linux) X-Provags-ID: kundenserver.de abuse@kundenserver.de login:d7ab225b98a136e1c2910381f940ecb9 X-Mailman-Approved-At: Thu, 27 Apr 2006 12:58:47 -0400 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:34684 Archived-At: Eli Zaretskii writes: >> From: Dieter Wilhelm >> 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. That was my feeling (Look, I'm somewhat pampered through the excellent Emacs documentation) 8-) > 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. Oh holly ... I didn't read it carefully and confused Return with Render, I'm sorry (using GNU Emacs 22.0.50.3 (i686-pc-linux-gnu, X toolkit, Xaw3d scroll bars) of 2006-04-23 on hans, but not using the scroll bars ;-)). > As for the other two, the return nil, i.e. nothing, so I think it's > okay to say nothing about the (absent) return Well, I realised that the coder expressly specified nil as the return value, so I thought it somehow important. Then you suggest the following guideline: Document all return values *except* nil. When this is generally accommodated I'm perfectly happy with it. By the way, is nil in Elisp analogous to void in C/C++? Does an uninitialised variable represent also nil? Strange: (defvar foo) foo says void value of foo? Wait a moment, I think I don't know what I'm taking about, I'll better read in the Elisp manual what actually nil means. >> Should I report this as bugs or is this a bit over the top? > > ...feel free to report if you disagree with my reasoning. No thanks, this would be self defeating. -- Best wishes Dieter Wilhelm