No return value in doc string

No return value in doc string

[Dieter Wilhelm]

Hi

Is there any policy for the documentation string of the return value?
The Elisp programming guidelines just mention that the documentation
string for functions should answer the question "What does this
function do?".  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').

Should I report this as bugs or is this a bit over the top?

-- 
Best wishes

     Dieter Wilhelm

Re: No return value in doc string

[Eli Zaretskii]

> 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.

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

Re: No return value in doc string

[Stefan Monnier]

> Is there any policy for the documentation string of the return value?
> The Elisp programming guidelines just mention that the documentation
> string for functions should answer the question "What does this
> function do?".  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').

When called interactively, a function's return value is simply ignored, so
if a function is expected to only be called interactively, there is no
reason to document the return value.

Also if the function makes no effort to return anything useful, it
might be better not to document what the return value happens to be.

> Should I report this as bugs or is this a bit over the top?

Your call,


        Stefan

Re: No return value in doc string

[Dieter Wilhelm]

Stefan Monnier <monnier@iro.umontreal.ca> writes:
>
> When called interactively, a function's return value is simply ignored, so
> if a function is expected to only be called interactively, there is no
> reason to document the return value.

Thank you, this is a point I didn't realise.

> Also if the function makes no effort to return anything useful, it
> might be better not to document what the return value happens to be.

But has the disadvantage that the uninitiated and insecure (my
example) may suspect a documentation flaw.

>> Should I report this as bugs or is this a bit over the top?

> Your call,

Eli Z. convinced me already not to waste anybodies time with it.

-- 
Best wishes

     Dieter Wilhelm

Re: No return value in doc string

[Miles Bader]

Dieter Wilhelm <dieter@duenenhof-wilhelm.de> writes:
>> Also if the function makes no effort to return anything useful, it
>> might be better not to document what the return value happens to be.
>
> But has the disadvantage that the uninitiated and insecure (my
> example) may suspect a documentation flaw.

They'll have to learn to deal with that.

It's a fairly general rule in computer programming:  if something is not
mentioned in the documentation (or some more formal interface
description), you cannot make assumptions about it.  [In practice of
course, you _have_ to make _some_ assumptions, but learning which you
can make and which you can't is an important part of learning to program
in a particular environment.]

-Miles
-- 
"Most attacks seem to take place at night, during a rainstorm, uphill,
 where four map sheets join."   -- Anon. British Officer in WW I