Improve docs of some transposition functions.

* simple.el (transpose-subr): Give it a doc-string.

* textmodes/paragraphs.el (transpose-paragraphs, transpose-sentences):
Doc fixes.

3 files changed, 32 insertions, 3 deletions

diff --git a/lisp/ChangeLog b/lisp/ChangeLog
index 702f283a9ff..0b764b3a452 100644
--- a/lisp/ChangeLog
+++ b/lisp/ChangeLog
@@ -1,3 +1,10 @@
+2010-02-13  Glenn Morris  <rgm@gnu.org>
+
+        * simple.el (transpose-subr): Give it a doc-string.
+
+        * textmodes/paragraphs.el (transpose-paragraphs, transpose-sentences):
+        Doc fixes.
+
 2010-02-12  Juri Linkov  <juri@jurta.org>
 
         * arc-mode.el (archive-unique-fname): Make directories for nested
diff --git a/lisp/simple.el b/lisp/simple.el
index 5de308ee229..b16794f2770 100644
--- a/lisp/simple.el
+++ b/lisp/simple.el
@@ -4854,7 +4854,18 @@ With argument 0, interchanges line point is in with line mark is in."
                        (forward-line arg))))
                   arg))
 
+;; FIXME seems to leave point BEFORE the current object when ARG = 0,
+;; which seems inconsistent with the ARG /= 0 case.
+;; FIXME document SPECIAL.
 (defun transpose-subr (mover arg &optional special)
+  "Subroutine to do the work of transposing objects.
+Works for lines, sentences, paragraphs, etc.  MOVER is a function that
+moves forward by units of the given object (e.g. forward-sentence,
+forward-paragraph).  If ARG is zero, exchanges the current object
+with the one containing mark.  If ARG is an integer, moves the
+current object past ARG following (if ARG is positive) or
+preceding (if ARG is negative) objects, leaving point after the
+current object."
   (let ((aux (if special mover
                (lambda (x)
                  (cons (progn (funcall mover x) (point))
diff --git a/lisp/textmodes/paragraphs.el b/lisp/textmodes/paragraphs.el
index 51f893af6e6..2c698a836fe 100644
--- a/lisp/textmodes/paragraphs.el
+++ b/lisp/textmodes/paragraphs.el
@@ -1,7 +1,8 @@
 ;;; paragraphs.el --- paragraph and sentence parsing
 
 ;; Copyright (C) 1985, 1986, 1987, 1991, 1994, 1995, 1996, 1997, 1999, 2000,
-;;   2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 Free Software Foundation, Inc.
+;;   2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010
+;;   Free Software Foundation, Inc.
 
 ;; Maintainer: FSF
 ;; Keywords: wp
@@ -409,7 +410,12 @@ negative arg -N means kill forward to Nth end of paragraph."
   (kill-region (point) (progn (backward-paragraph arg) (point))))
 
 (defun transpose-paragraphs (arg)
-  "Interchange this (or next) paragraph with previous one."
+  "Interchange the current paragraph with the next one.
+With prefix argument ARG a non-zero integer, moves the current
+paragraph past ARG paragraphs, leaving point after the current paragraph.
+If ARG is positive, moves the current paragraph forwards, if
+ARG is negative moves it backwards.  If ARG is zero, exchanges
+the current paragraph with the one containing the mark."
   (interactive "*p")
   (transpose-subr 'forward-paragraph arg))
 
@@ -509,7 +515,12 @@ ones already marked."
    nil t))
 
 (defun transpose-sentences (arg)
-  "Interchange this (next) and previous sentence."
+  "Interchange the current sentence with the next one.
+With prefix argument ARG a non-zero integer, moves the current
+sentence past ARG sentences, leaving point after the current sentence.
+If ARG is positive, moves the current sentence forwards, if
+ARG is negative moves it backwards.  If ARG is zero, exchanges
+the current sentence with the one containing the mark."
   (interactive "*p")
   (transpose-subr 'forward-sentence arg))