unofficial mirror of emacs-devel@gnu.org 
 help / color / mirror / code / Atom feed
* Re: [Emacs-diffs] /srv/bzr/emacs/trunk r104642: * src/process.c (Fset_process_buffer): Clarify return value in docstring.
       [not found] <E1QYeLs-00050O-9O@colonialone.fsf.org>
@ 2011-06-20 14:26 ` Stefan Monnier
  2011-06-20 16:16   ` Juanma Barranquero
  2011-06-21 16:00   ` Deniz Dogan
  0 siblings, 2 replies; 12+ messages in thread
From: Stefan Monnier @ 2011-06-20 14:26 UTC (permalink / raw)
  To: Deniz Dogan; +Cc: emacs-devel

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



^ permalink raw reply	[flat|nested] 12+ messages in thread

* Re: [Emacs-diffs] /srv/bzr/emacs/trunk r104642: * src/process.c (Fset_process_buffer): Clarify return value in docstring.
  2011-06-20 14:26 ` [Emacs-diffs] /srv/bzr/emacs/trunk r104642: * src/process.c (Fset_process_buffer): Clarify return value in docstring Stefan Monnier
@ 2011-06-20 16:16   ` Juanma Barranquero
  2011-06-20 17:53     ` Stefan Monnier
  2011-06-21 16:00   ` Deniz Dogan
  1 sibling, 1 reply; 12+ messages in thread
From: Juanma Barranquero @ 2011-06-20 16:16 UTC (permalink / raw)
  To: Stefan Monnier; +Cc: Deniz Dogan, emacs-devel

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



^ permalink raw reply	[flat|nested] 12+ messages in thread

* Re: [Emacs-diffs] /srv/bzr/emacs/trunk r104642: * src/process.c (Fset_process_buffer): Clarify return value in docstring.
  2011-06-20 16:16   ` Juanma Barranquero
@ 2011-06-20 17:53     ` Stefan Monnier
  2011-06-20 19:53       ` Juanma Barranquero
  2011-06-21  4:10       ` Stephen J. Turnbull
  0 siblings, 2 replies; 12+ messages in thread
From: Stefan Monnier @ 2011-06-20 17:53 UTC (permalink / raw)
  To: Juanma Barranquero; +Cc: Deniz Dogan, emacs-devel

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



^ permalink raw reply	[flat|nested] 12+ messages in thread

* Re: [Emacs-diffs] /srv/bzr/emacs/trunk r104642: * src/process.c (Fset_process_buffer): Clarify return value in docstring.
  2011-06-20 17:53     ` Stefan Monnier
@ 2011-06-20 19:53       ` Juanma Barranquero
  2011-06-21 14:13         ` Stefan Monnier
  2011-06-21  4:10       ` Stephen J. Turnbull
  1 sibling, 1 reply; 12+ messages in thread
From: Juanma Barranquero @ 2011-06-20 19:53 UTC (permalink / raw)
  To: Stefan Monnier; +Cc: Deniz Dogan, emacs-devel

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



^ permalink raw reply	[flat|nested] 12+ messages in thread

* Re: [Emacs-diffs] /srv/bzr/emacs/trunk r104642: * src/process.c (Fset_process_buffer): Clarify return value in docstring.
  2011-06-20 17:53     ` Stefan Monnier
  2011-06-20 19:53       ` Juanma Barranquero
@ 2011-06-21  4:10       ` Stephen J. Turnbull
  1 sibling, 0 replies; 12+ messages in thread
From: Stephen J. Turnbull @ 2011-06-21  4:10 UTC (permalink / raw)
  To: Stefan Monnier; +Cc: Juanma Barranquero, Deniz Dogan, emacs-devel

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.



^ permalink raw reply	[flat|nested] 12+ messages in thread

* Re: [Emacs-diffs] /srv/bzr/emacs/trunk r104642: * src/process.c (Fset_process_buffer): Clarify return value in docstring.
  2011-06-20 19:53       ` Juanma Barranquero
@ 2011-06-21 14:13         ` Stefan Monnier
  2011-06-21 14:30           ` Juanma Barranquero
  0 siblings, 1 reply; 12+ messages in thread
From: Stefan Monnier @ 2011-06-21 14:13 UTC (permalink / raw)
  To: Juanma Barranquero; +Cc: Deniz Dogan, emacs-devel

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



^ permalink raw reply	[flat|nested] 12+ messages in thread

* Re: [Emacs-diffs] /srv/bzr/emacs/trunk r104642: * src/process.c (Fset_process_buffer): Clarify return value in docstring.
  2011-06-21 14:13         ` Stefan Monnier
@ 2011-06-21 14:30           ` Juanma Barranquero
  2011-06-21 16:33             ` Stefan Monnier
  0 siblings, 1 reply; 12+ messages in thread
From: Juanma Barranquero @ 2011-06-21 14:30 UTC (permalink / raw)
  To: Stefan Monnier; +Cc: Deniz Dogan, emacs-devel

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



^ permalink raw reply	[flat|nested] 12+ messages in thread

* Re: [Emacs-diffs] /srv/bzr/emacs/trunk r104642: * src/process.c (Fset_process_buffer): Clarify return value in docstring.
  2011-06-20 14:26 ` [Emacs-diffs] /srv/bzr/emacs/trunk r104642: * src/process.c (Fset_process_buffer): Clarify return value in docstring Stefan Monnier
  2011-06-20 16:16   ` Juanma Barranquero
@ 2011-06-21 16:00   ` Deniz Dogan
  1 sibling, 0 replies; 12+ messages in thread
From: Deniz Dogan @ 2011-06-21 16:00 UTC (permalink / raw)
  To: Stefan Monnier; +Cc: emacs-devel

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



^ permalink raw reply	[flat|nested] 12+ messages in thread

* Re: [Emacs-diffs] /srv/bzr/emacs/trunk r104642: * src/process.c (Fset_process_buffer): Clarify return value in docstring.
  2011-06-21 14:30           ` Juanma Barranquero
@ 2011-06-21 16:33             ` Stefan Monnier
  2011-06-21 16:39               ` Juanma Barranquero
  2011-06-21 20:17               ` Deniz Dogan
  0 siblings, 2 replies; 12+ messages in thread
From: Stefan Monnier @ 2011-06-21 16:33 UTC (permalink / raw)
  To: Juanma Barranquero; +Cc: Deniz Dogan, emacs-devel

> 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



^ permalink raw reply	[flat|nested] 12+ messages in thread

* Re: [Emacs-diffs] /srv/bzr/emacs/trunk r104642: * src/process.c (Fset_process_buffer): Clarify return value in docstring.
  2011-06-21 16:33             ` Stefan Monnier
@ 2011-06-21 16:39               ` Juanma Barranquero
  2011-06-21 20:17               ` Deniz Dogan
  1 sibling, 0 replies; 12+ messages in thread
From: Juanma Barranquero @ 2011-06-21 16:39 UTC (permalink / raw)
  To: Stefan Monnier; +Cc: Deniz Dogan, emacs-devel

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



^ permalink raw reply	[flat|nested] 12+ messages in thread

* Re: [Emacs-diffs] /srv/bzr/emacs/trunk r104642: * src/process.c (Fset_process_buffer): Clarify return value in docstring.
  2011-06-21 16:33             ` Stefan Monnier
  2011-06-21 16:39               ` Juanma Barranquero
@ 2011-06-21 20:17               ` Deniz Dogan
  2011-06-22  1:59                 ` Stefan Monnier
  1 sibling, 1 reply; 12+ messages in thread
From: Deniz Dogan @ 2011-06-21 20:17 UTC (permalink / raw)
  To: Stefan Monnier; +Cc: Juanma Barranquero, emacs-devel

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



^ permalink raw reply	[flat|nested] 12+ messages in thread

* Re: [Emacs-diffs] /srv/bzr/emacs/trunk r104642: * src/process.c (Fset_process_buffer): Clarify return value in docstring.
  2011-06-21 20:17               ` Deniz Dogan
@ 2011-06-22  1:59                 ` Stefan Monnier
  0 siblings, 0 replies; 12+ messages in thread
From: Stefan Monnier @ 2011-06-22  1:59 UTC (permalink / raw)
  To: Deniz Dogan; +Cc: Juanma Barranquero, emacs-devel

> 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



^ permalink raw reply	[flat|nested] 12+ messages in thread

end of thread, other threads:[~2011-06-22  1:59 UTC | newest]

Thread overview: 12+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
     [not found] <E1QYeLs-00050O-9O@colonialone.fsf.org>
2011-06-20 14:26 ` [Emacs-diffs] /srv/bzr/emacs/trunk r104642: * src/process.c (Fset_process_buffer): Clarify return value in docstring Stefan Monnier
2011-06-20 16:16   ` Juanma Barranquero
2011-06-20 17:53     ` Stefan Monnier
2011-06-20 19:53       ` Juanma Barranquero
2011-06-21 14:13         ` Stefan Monnier
2011-06-21 14:30           ` Juanma Barranquero
2011-06-21 16:33             ` Stefan Monnier
2011-06-21 16:39               ` Juanma Barranquero
2011-06-21 20:17               ` Deniz Dogan
2011-06-22  1:59                 ` Stefan Monnier
2011-06-21  4:10       ` Stephen J. Turnbull
2011-06-21 16:00   ` Deniz Dogan

Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).