Fix return value of `defun' and un-define it.

* src/data.c (Fdefalias): Return `symbol'.
* doc/lispref/functions.texi (Defining Functions):
* doc/lispref/macros.texi (Defining Macros): Un-define the return value of
`defun', `defmacro' and `defalias'.

Fixes: debbugs:11686

doc/lispref/ChangeLog

+2012-06-18  Stefan Monnier  <monnier@iro.umontreal.ca>
+
+	* functions.texi (Defining Functions):
+	* macros.texi (Defining Macros): Un-define the return value of `defun',
+	`defmacro' and `defalias'.
+
 2012-06-17  Chong Yidong  <cyd@gnu.org>
 
 	* elisp.texi: Remove urlcolor setting.

doc/lispref/functions.texi

@@ -530,8 +530,7 @@ defines the symbol @var{name} as a function that looks like this:
 @end example
 
 @code{defun} stores this lambda expression in the function cell of
-@var{name}.  It returns the value @var{name}, but usually we ignore this
-value.
+@var{name}.  Its return value is @emph{undefined}.
 
 As described previously, @var{argument-list} is a list of argument
 names and may include the keywords @code{&optional} and @code{&rest}.
@@ -543,9 +542,6 @@ Here are some examples:
 @example
 @group
 (defun foo () 5)
-     @result{} foo
-@end group
-@group
 (foo)
      @result{} 5
 @end group
@@ -553,9 +549,6 @@ Here are some examples:
 @group
 (defun bar (a &optional b &rest c)
     (list a b c))
-     @result{} bar
-@end group
-@group
 (bar 1 2 3 4 5)
      @result{} (1 2 (3 4 5))
 @end group
@@ -576,7 +569,6 @@ Here are some examples:
   (forward-word 1)
   (backward-char 1)
   (capitalize-word 1))
-     @result{} capitalize-backwards
 @end group
 @end example
 
@@ -593,7 +585,7 @@ redefinition from unintentional redefinition.
 @anchor{Definition of defalias}
 This special form defines the symbol @var{name} as a function, with
 definition @var{definition} (which can be any valid Lisp function).
-It returns @var{definition}.
+Its return value is @emph{undefined}.
 
 If @var{docstring} is non-@code{nil}, it becomes the function
 documentation of @var{name}.  Otherwise, any documentation provided by
@@ -1015,9 +1007,6 @@ function.
 @example
 @group
 (defun bar (n) (+ n 2))
-     @result{} bar
-@end group
-@group
 (symbol-function 'bar)
      @result{} (lambda (n) (+ n 2))
 @end group
@@ -1063,9 +1052,6 @@ subsequent attempt to access this cell will cause a
 @example
 @group
 (defun foo (x) x)
-     @result{} foo
-@end group
-@group
 (foo 1)
      @result{}1
 @end group

doc/lispref/macros.texi

@@ -113,7 +113,6 @@ uses this feature.
 @group
 (defmacro inc (var)
     (list 'setq var (list '1+ var)))
-     @result{} inc
 @end group
 
 @group
@@ -124,7 +123,6 @@ uses this feature.
 @group
 (defmacro inc2 (var1 var2)
     (list 'progn (list 'inc var1) (list 'inc var2)))
-     @result{} inc2
 @end group
 
 @group
@@ -207,9 +205,8 @@ like this:
 @end example
 
 (Note that the @sc{cdr} of this list is a function---a lambda expression.)
-This macro object is stored in the function cell of @var{name}.  The
-value returned by evaluating the @code{defmacro} form is @var{name}, but
-usually we ignore this value.
+This macro object is stored in the function cell of @var{name}.  Its return
+value is @emph{undefined}.
 
 The shape and meaning of @var{argument-list} is the same as in a
 function, and the keywords @code{&rest} and @code{&optional} may be used
@@ -342,7 +339,6 @@ For example, (for i from 1 to 10 do (print i))."
               (cons (list '<= var final)
                     (append body (list (list 'inc var)))))))
 @end group
-@result{} for
 
 @group
 (for i from 1 to 3 do
@@ -512,7 +508,6 @@ it.  Here is an example:
 @group
 (defmacro foo (a)
   (list 'setq (eval a) t))
-     @result{} foo
 @end group
 @group
 (setq x 'b)

etc/NEWS

@@ -429,6 +429,8 @@ still be supported for Emacs 24.x.
 
 * Lisp changes in Emacs 24.2
 
+** The return value of `defalias' has changed and is now undefined.
+
 ** `defun' also accepts a (declare DECLS) form, like `defmacro'.
 The interpretation of the DECLS is determined by `defun-declarations-alist'.
 

lisp/emacs-lisp/byte-run.el

@@ -123,7 +123,8 @@ the list ARGS... as it appears in the expression,
 and the result should be a form to be evaluated instead of the original.
 DECL is a declaration, optional, of the form (declare DECLS...) where
 DECLS is a list of elements of the form (PROP . VALUES).  These are
-interpreted according to `macro-declarations-alist'."
+interpreted according to `macro-declarations-alist'.
+The return value is undefined."
        (if (stringp docstring) nil
          (if decl (setq body (cons decl body)))
          (setq decl docstring)
@@ -158,6 +159,7 @@ See also the function `interactive'.
 DECL is a declaration, optional, of the form (declare DECLS...) where
 DECLS is a list of elements of the form (PROP . VALUES).  These are
 interpreted according to `defun-declarations-alist'.
+The return value is undefined.
 
 \(fn NAME ARGLIST &optional DOCSTRING DECL &rest BODY)"
   ;; We can't just have `decl' as an &optional argument, because we need

src/ChangeLog

+2012-06-18  Stefan Monnier  <monnier@iro.umontreal.ca>
+
+	* data.c (Fdefalias): Return `symbol' (bug#11686).
+
 2012-06-18  Martin Rudalics  <rudalics@gmx.at>
 
 	* buffer.c (Fkill_buffer): Don't throw an error when the buffer
-	gets killed during executing of this function (Bug#11665).  Try
-	to always return Qt when the buffer has been actually killed.
+	gets killed during executing of this function (Bug#11665).
+	Try to always return Qt when the buffer has been actually killed.
 	(Vkill_buffer_query_functions): In doc-string say that functions
 	run by this hook should not change the current buffer.
 
@@ -56,8 +60,8 @@
 	(x_draw_glyph_string): Use them.
 	* xfaces.c (Qline, Qwave): New Lisp objects.
 	(check_lface_attrs, merge_face_ref)
-	(Finternal_set_lisp_face_attribute, realize_x_face): Handle
-	wave-style underline face attributes.
+	(Finternal_set_lisp_face_attribute, realize_x_face):
+	Handle wave-style underline face attributes.
 	* xterm.c (x_draw_underwave): New function.
 	(x_draw_glyph_string): Use it.
 
@@ -130,8 +134,8 @@
 
 2012-06-16  Eli Zaretskii  <eliz@gnu.org>
 
-	* xdisp.c (set_cursor_from_row): Don't dereference glyphs_end.  If
-	all the glyphs of the glyph row came from strings, and we have no
+	* xdisp.c (set_cursor_from_row): Don't dereference glyphs_end.
+	If all the glyphs of the glyph row came from strings, and we have no
 	cursor positioning clues, put the cursor on the first glyph of the
 	row.
 	(handle_face_prop): Use chunk-relative overlay string index when
@@ -164,8 +168,8 @@
 	Simplify under the assumption that USE_2_TAGS_FOR_INTS is defined.
 	(INTTYPEBITS): New macro, for clarity.
 	(INTMASK, MOST_POSITIVE_FIXNUM): Use it.
-	(LISP_INT1_TAG, LISP_STRING_TAG, LISP_INT_TAG_P): Simplify
-	now that USE_LSB_TAG is always defined.
+	(LISP_INT1_TAG, LISP_STRING_TAG, LISP_INT_TAG_P):
+	Simplify now that USE_LSB_TAG is always defined.
 	(TYPEMASK, XINT) [USE_LSB_TAG]: Remove unnecessary cast.
 	(make_number) [!USE_LSB_TAG]: Use INTMASK; that's simpler.
 
@@ -183,11 +187,11 @@
 	* lisp.h (Lisp_Object) [CHECK_LISP_OBJECT_TYPE]: Define as struct
 	instead of union.
 	(XLI, XIL): Define.
-	(XHASH, XTYPE, XINT, XUINT, make_number, XSET, XPNTR, XUNTAG): Use
-	them.
-	* emacs.c (gdb_use_struct): Renamed from gdb_use_union.
+	(XHASH, XTYPE, XINT, XUINT, make_number, XSET, XPNTR, XUNTAG):
+	Use them.
+	* emacs.c (gdb_use_struct): Rename from gdb_use_union.
 	* .gdbinit: Check gdb_use_struct instead of gdb_use_union.
-	* alloc.c (widen_to_Lisp_Object): Removed.
+	* alloc.c (widen_to_Lisp_Object): Remove.
 	(mark_memory): Use XIL instead of widen_to_Lisp_Object.
 	* frame.c (delete_frame): Remove outdated comment.
 	* w32fns.c (Fw32_register_hot_key): Use XLI instead of checking

src/data.c

@@ -637,8 +637,9 @@ DEFUN ("fset", Ffset, Sfset, 2, 2, 0,
     Fput (symbol, Qautoload, XCDR (function));
 
   XSYMBOL (symbol)->function = definition;
-  /* Handle automatic advice activation */
-  if (CONSP (XSYMBOL (symbol)->plist) && !NILP (Fget (symbol, Qad_advice_info)))
+  /* Handle automatic advice activation.  */
+  if (CONSP (XSYMBOL (symbol)->plist)
+      && !NILP (Fget (symbol, Qad_advice_info)))
     {
       call2 (Qad_activate_internal, symbol, Qnil);
       definition = XSYMBOL (symbol)->function;
@@ -647,11 +648,12 @@ DEFUN ("fset", Ffset, Sfset, 2, 2, 0,
 }
 
 DEFUN ("defalias", Fdefalias, Sdefalias, 2, 3, 0,
-       doc: /* Set SYMBOL's function definition to DEFINITION, and return DEFINITION.
+       doc: /* Set SYMBOL's function definition to DEFINITION.
 Associates the function with the current load file, if any.
 The optional third argument DOCSTRING specifies the documentation string
 for SYMBOL; if it is omitted or nil, SYMBOL uses the documentation string
-determined by DEFINITION.  */)
+determined by DEFINITION.
+The return value is undefined.  */)
   (register Lisp_Object symbol, Lisp_Object definition, Lisp_Object docstring)
 {
   CHECK_SYMBOL (symbol);
@@ -666,7 +668,10 @@ determined by DEFINITION.  */)
   LOADHIST_ATTACH (Fcons (Qdefun, symbol));
   if (!NILP (docstring))
     Fput (symbol, Qfunction_documentation, docstring);
-  return definition;
+  /* We used to return `definition', but now that `defun' and `defmacro' expand
+     to a call to `defalias', we return `symbol' for backward compatibility
+     (bug#11686).  */
+  return symbol;
 }
 
 DEFUN ("setplist", Fsetplist, Ssetplist, 2, 2, 0,