Re: [Emacs-diffs] /srv/bzr/emacs/trunk r104642: * src/process.c (Fset_process_buffer): Clarify return value in docstring.

Re: [Emacs-diffs] /srv/bzr/emacs/trunk r104642: * src/process.c (Fset_process_buffer): Clarify return value in docstring.

[Stefan Monnier]

> -       doc: /* Set buffer associated with PROCESS to BUFFER (a buffer, or nil).  */)
> +       doc: /* Set buffer associated with PROCESS to BUFFER (a buffer, or nil).
> +Return BUFFER.  */)

Actually, I generally prefer not to document the accidental return value
of side-effecting functions.  It's poor style anyway to use that return
value, in my book.


        Stefan

Re: [Emacs-diffs] /srv/bzr/emacs/trunk r104642: * src/process.c (Fset_process_buffer): Clarify return value in docstring.

[Juanma Barranquero]

On Mon, Jun 20, 2011 at 16:26, Stefan Monnier <monnier@iro.umontreal.ca> wrote:
>> -       doc: /* Set buffer associated with PROCESS to BUFFER (a buffer, or nil).  */)
>> +       doc: /* Set buffer associated with PROCESS to BUFFER (a buffer, or nil).
>> +Return BUFFER.  */)
>
> Actually, I generally prefer not to document the accidental return value
> of side-effecting functions.

What's accidental in

  return buffer;

?

    Juanma

Re: [Emacs-diffs] /srv/bzr/emacs/trunk r104642: * src/process.c (Fset_process_buffer): Clarify return value in docstring.

[Stefan Monnier]

>> Actually, I generally prefer not to document the accidental return value
>> of side-effecting functions.

> What's accidental in
>   return buffer;
> ?

That the author could just as well have written "return Qnil;" or
various other options.
I can't find a single example of Elisp code in Emacs that does not
ignore the return value of set-process-buffer (and that's a good thing).


        Stefan

Re: [Emacs-diffs] /srv/bzr/emacs/trunk r104642: * src/process.c (Fset_process_buffer): Clarify return value in docstring.

[Juanma Barranquero]

On Mon, Jun 20, 2011 at 19:53, Stefan Monnier <monnier@iro.umontreal.ca> wrote:

> That the author could just as well have written "return Qnil;" or
> various other options.

"return Qnil;" is rarely useful. "return buffer;" could be.

> I can't find a single example of Elisp code in Emacs that does not
> ignore the return value of set-process-buffer

Hardly surprising, as it was undocumented.

> (and that's a good thing).

Perhaps. Do you oppose also to using the return value of other
side-effecting functions or special forms, like `setq'? Because
there's no shortage of "(if (setq", "(and (setq", "(or (setq" in the
sources (341, 387 and 54 instances, respectively).

    Juanma

Re: [Emacs-diffs] /srv/bzr/emacs/trunk r104642: * src/process.c (Fset_process_buffer): Clarify return value in docstring.

[Stephen J. Turnbull]

Stefan Monnier writes:
 > >> Actually, I generally prefer not to document the accidental return value
 > >> of side-effecting functions.
 > 
 > > What's accidental in
 > >   return buffer;
 > > ?
 > 
 > That the author could just as well have written "return Qnil;" or
 > various other options.

Well, since the DEFUN macro basically requires a return value, and all
functions defined in Lisp do return something, you probably ought to
say that a function should return nil unless there's an obviously good
value to return.

 > I can't find a single example of Elisp code in Emacs that does not
 > ignore the return value of set-process-buffer (and that's a good thing).

Not necessarily a good thing in Elisp.  Like it or not, Elisp has
never made a strong distinction between functions that return values
and functions that have side effects.

While you may prefer the style

    (let ((buf (get-buffer-create "buffer for process")))
      (set-process-buffer proc buf)
      (do-buffing buf))

in Elisp it's common enough to see the style

      (do-buffing
       (set-process-buffer proc
                           (get-buffer-create "buffer for process")))

and I don't really see anything wrong with that in Elisp.

Of course as a matter of design, in many cases it's preferable to
return nil now, and think about what a useful return value might be
after we see use cases for the function.

Re: [Emacs-diffs] /srv/bzr/emacs/trunk r104642: * src/process.c (Fset_process_buffer): Clarify return value in docstring.

[Stefan Monnier]

>> I can't find a single example of Elisp code in Emacs that does not
>> ignore the return value of set-process-buffer
> Hardly surprising, as it was undocumented.

People usually aren't afraid to use undocumented features.

>> (and that's a good thing).
> Perhaps. Do you oppose also to using the return value of other
> side-effecting functions or special forms,

As a general rule, yes.

> like `setq'? Because there's no shortage of "(if (setq", "(and (setq",
> "(or (setq" in the sources (341, 387 and 54 instances, respectively).

Indeed, setq is used this way fairly often, so it's pointless to try and
oppose it.  As a matter of fact, I do use this sometimes myself.


        Stefan

Re: [Emacs-diffs] /srv/bzr/emacs/trunk r104642: * src/process.c (Fset_process_buffer): Clarify return value in docstring.

[Juanma Barranquero]

On Tue, Jun 21, 2011 at 16:13, Stefan Monnier <monnier@iro.umontreal.ca> wrote:

> People usually aren't afraid to use undocumented features.

And if they were 300+ uses of set-process-buffer in the sources,
instead of 19, someone would have.

> As a general rule, yes.

What about `display-buffer'? It certainly exists for its side effect,
but it returns the window, a fact which is both documented and used.
If it were a new function, would you oppose doing so?

I'm not arguing, mind you, just trying to understand why it is OK for
some functions whose whole purpose is side-effects to return a useful
value, and not OK for others.

    Juanma

Re: [Emacs-diffs] /srv/bzr/emacs/trunk r104642: * src/process.c (Fset_process_buffer): Clarify return value in docstring.

[Deniz Dogan]

On 2011-06-20 16:26, Stefan Monnier wrote:
>> -       doc: /* Set buffer associated with PROCESS to BUFFER (a buffer, or nil).  */)
>> +       doc: /* Set buffer associated with PROCESS to BUFFER (a buffer, or nil).
>> +Return BUFFER.  */)
>
> Actually, I generally prefer not to document the accidental return value
> of side-effecting functions.  It's poor style anyway to use that return
> value, in my book.
>

I don't mind at all should you revert the change, I just figured it 
could be useful for others to know.

For what it's worth, here's the code where I use the return value (not 
in GNU Emacs):

(defun dirc-setup-server-buffer (process)
   "Set up the server buffer for PROCESS."
   (let ((buffer (set-process-buffer
                  process
                  (pop-to-buffer-same-window
                   (dirc-make-process-buffer-name process)))))
     (with-current-buffer buffer
       (set (make-local-variable 'dirc-buffer-type) 'server)
       (set (make-local-variable 'dirc-process process)))))

/Deniz

Re: [Emacs-diffs] /srv/bzr/emacs/trunk r104642: * src/process.c (Fset_process_buffer): Clarify return value in docstring.

[Stefan Monnier]

> What about `display-buffer'? It certainly exists for its side effect,
> but it returns the window, a fact which is both documented and used.
> If it were a new function, would you oppose doing so?

No, I do not systematically oppose side-effecting functions which return
a value as well.  That would be much too drastic (e.g. how would you
figure out which window was used by `display-buffer'?).
I;.e. the return value is really indispensable.  Contrast this with
set-process-buffer whose return value is always available to the caller
before even calling it.


        Stefan

Re: [Emacs-diffs] /srv/bzr/emacs/trunk r104642: * src/process.c (Fset_process_buffer): Clarify return value in docstring.

[Juanma Barranquero]

On Tue, Jun 21, 2011 at 18:33, Stefan Monnier <monnier@iro.umontreal.ca> wrote:

> No, I do not systematically oppose side-effecting functions which return
> a value as well.  That would be much too drastic (e.g. how would you
> figure out which window was used by `display-buffer'?).
> I;.e. the return value is really indispensable.  Contrast this with
> set-process-buffer whose return value is always available to the caller
> before even calling it.

OK, that makes sense.

Thanks,

    Juanma

Re: [Emacs-diffs] /srv/bzr/emacs/trunk r104642: * src/process.c (Fset_process_buffer): Clarify return value in docstring.

[Deniz Dogan]

On 2011-06-21 18:33, Stefan Monnier wrote:
>> What about `display-buffer'? It certainly exists for its side effect,
>> but it returns the window, a fact which is both documented and used.
>> If it were a new function, would you oppose doing so?
>
> No, I do not systematically oppose side-effecting functions which return
> a value as well.  That would be much too drastic (e.g. how would you
> figure out which window was used by `display-buffer'?).
> I;.e. the return value is really indispensable.  Contrast this with
> set-process-buffer whose return value is always available to the caller
> before even calling it.
>

I'm just wondering: can I rely on `set-process-buffer' always returning 
the buffer from now on or is it prone to change given the fact that it 
is "accidental"?

Thanks,
Deniz

Re: [Emacs-diffs] /srv/bzr/emacs/trunk r104642: * src/process.c (Fset_process_buffer): Clarify return value in docstring.

[Stefan Monnier]

> I'm just wondering: can I rely on `set-process-buffer' always returning the
> buffer from now on or is it prone to change given the fact that it is
> "accidental"?

Now that you documented it, you can probably rely on it.
But if I undocument it before the release, then there's a risk it
might change.  If I were you I'd use

(defun dirc-setup-server-buffer (process)
  "Set up the server buffer for PROCESS."
  (let ((buffer (pop-to-buffer-same-window
                  (dirc-make-process-buffer-name process))))
    (set-process-buffer process buffer)))
    (with-current-buffer buffer
      (set (make-local-variable 'dirc-buffer-type) 'server)
      (set (make-local-variable 'dirc-process process)))))

which I find more readable and where you don't need to worry about it.


        Stefan