[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: No return value in doc string
From: |
Eli Zaretskii |
Subject: |
Re: No return value in doc string |
Date: |
Wed, 26 Apr 2006 20:34:07 +0300 |
> From: Dieter Wilhelm <dieter@duenenhof-wilhelm.de>
> 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.