Re: No return value in doc string

[Dieter Wilhelm]

Eli Zaretskii <eliz@gnu.org> writes:
>> From: Dieter Wilhelm <dieter@duenenhof-wilhelm.de>
>> 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