Misc docfixes.

Suggested by Martin Rudalics.

* doc/lispref/display.texi (Face Functions): Fix define-obsolete-face-alias.

* doc/lispref/functions.texi (Obsolete Functions): Fix doc for
set-advertised-calling-convention.

* doc/lispref/modes.texi (Mode Help): Fix describe-mode.

* doc/lispref/variables.texi (Variable Aliases): Fix make-obsolete-variable.

* lisp/help.el (describe-mode): Doc fix.

doc/lispref/ChangeLog

@@ -1,3 +1,14 @@
+2012-05-15  Chong Yidong  <cyd@gnu.org>
+
+	* functions.texi (Obsolete Functions): Fix doc for
+	set-advertised-calling-convention.
+
+	* modes.texi (Mode Help): Fix describe-mode.
+
+	* display.texi (Face Functions): Fix define-obsolete-face-alias.
+
+	* variables.texi (Variable Aliases): Fix make-obsolete-variable.
+
 2012-05-15  Martin Rudalics  <rudalics@gmx.at>
 
 	* commands.texi (Recursive Editing): recursive-edit is a

doc/lispref/display.texi

@@ -2663,11 +2663,13 @@ makes @code{modeline} an alias for the @code{mode-line} face.
 (put 'modeline 'face-alias 'mode-line)
 @end example
 
-@defun define-obsolete-face-alias obsolete-face current-face &optional when
-This function defines a face alias and marks it as obsolete, indicating
-that it may be removed in future.  The optional string @var{when}
-indicates when the face was made obsolete (for example, a release number).
-@end defun
+@defmac define-obsolete-face-alias obsolete-face current-face when
+This macro defines @code{obsolete-face} as an alias for
+@var{current-face}, and also marks it as obsolete, indicating that it
+may be removed in future.  @var{when} should be a string indicating
+when @code{obsolete-face} was made obsolete (usually a version number
+string).
+@end defmac
 
 @node Auto Faces
 @subsection Automatic Face Assignment

doc/lispref/functions.texi

@@ -1179,12 +1179,14 @@ equivalent to the following:
 In addition, you can mark a certain a particular calling convention
 for a function as obsolete:
 
-@defun set-advertised-calling-convention function signature
+@defun set-advertised-calling-convention function signature when
 This function specifies the argument list @var{signature} as the
 correct way to call @var{function}.  This causes the Emacs byte
 compiler to issue a warning whenever it comes across an Emacs Lisp
 program that calls @var{function} any other way (however, it will
-still allow the code to be byte compiled).
+still allow the code to be byte compiled).  @var{when} should be a
+string indicating when the variable was first made obsolete (usually a
+version number string).
 
 For instance, in old versions of Emacs the @code{sit-for} function
 accepted three arguments, like this
@@ -1199,7 +1201,7 @@ this:
 
 @example
 (set-advertised-calling-convention
-  'sit-for '(seconds &optional nodisp))
+  'sit-for '(seconds &optional nodisp) "22.1")
 @end example
 @end defun
 

doc/lispref/modes.texi

@@ -735,13 +735,15 @@ modes.  It is normally bound to @kbd{C-h m}.  It uses the value of the
 variable @code{major-mode} (@pxref{Major Modes}), which is why every
 major mode command needs to set that variable.
 
-@deffn Command describe-mode
-This function displays the documentation of the current major mode.
+@deffn Command describe-mode &optional buffer
+This command displays the documentation of the current buffer's major
+mode and minor modes.  It uses the @code{documentation} function to
+retrieve the documentation strings of the major and minor mode
+commands (@pxref{Accessing Documentation}).
 
-The @code{describe-mode} function calls the @code{documentation}
-function using the value of @code{major-mode} as an argument.  Thus, it
-displays the documentation string of the major mode command.
-(@xref{Accessing Documentation}.)
+If called from Lisp with a non-nil @var{buffer} argument, this
+function displays the documentation for that buffer's major and minor
+modes, rather than those of the current buffer.
 @end deffn
 
 @node Derived Modes

doc/lispref/variables.texi

@@ -1853,16 +1853,19 @@ variable with a new name.  @code{make-obsolete-variable} declares that
 the old name is obsolete and therefore that it may be removed at some
 stage in the future.
 
-@defun make-obsolete-variable obsolete-name current-name &optional when
+@defun make-obsolete-variable obsolete-name current-name when &optional access-type
 This function makes the byte compiler warn that the variable
-@var{obsolete-name} is obsolete.  If @var{current-name} is a symbol, it is
-the variable's new name; then the warning message says to use
-@var{current-name} instead of @var{obsolete-name}.  If @var{current-name}
-is a string, this is the message and there is no replacement variable.
+@var{obsolete-name} is obsolete.  If @var{current-name} is a symbol,
+it is the variable's new name; then the warning message says to use
+@var{current-name} instead of @var{obsolete-name}.  If
+@var{current-name} is a string, this is the message and there is no
+replacement variable.  @var{when} should be a string indicating when
+the variable was first made obsolete (usually a version number
+string).
 
-If provided, @var{when} should be a string indicating when the
-variable was first made obsolete---for example, a date or a release
-number.
+The optional argument @var{access-type}, if non-@code{nil}, should
+should specify the kind of access that will trigger obsolescence
+warnings; it can be either @code{get} or @code{set}.
 @end defun
 
   You can make two variables synonyms and declare one obsolete at the

lisp/ChangeLog

@@ -1,5 +1,7 @@
 2012-05-15  Chong Yidong  <cyd@gnu.org>
 
+	* help.el (describe-mode): Doc fix.
+
 	* net/gnutls.el (gnutls-min-prime-bits): Default to 256 (Bug#11267).
 
 2012-05-06  Troels Nielsen  <bn.troels@gmail.com>  (tiny change)

lisp/help.el

@@ -783,7 +783,10 @@ descriptions of the minor modes, each on a separate page.
 
 For this to work correctly for a minor mode, the mode's indicator
 variable \(listed in `minor-mode-alist') must also be a function
-whose documentation describes the minor mode."
+whose documentation describes the minor mode.
+
+If called from Lisp with a non-nil BUFFER argument, display
+documentation for the major and minor modes of that buffer."
   (interactive "@")
   (unless buffer (setq buffer (current-buffer)))
   (help-setup-xref (list #'describe-mode buffer)