[Emacs-diffs] /srv/bzr/emacs/trunk r99494: Improve docs of some transposition functions.

[Glenn Morris]

------------------------------------------------------------
revno: 99494
committer: Glenn Morris <address@hidden>
branch nick: trunk
timestamp: Sat 2010-02-13 11:29:25 -0800
message:
  Improve docs of some transposition functions.
  
  * simple.el (transpose-subr): Give it a doc-string.
  
  * textmodes/paragraphs.el (transpose-paragraphs, transpose-sentences):
  Doc fixes.
modified:
  lisp/ChangeLog
  lisp/simple.el
  lisp/textmodes/paragraphs.el

=== modified file 'lisp/ChangeLog'
--- a/lisp/ChangeLog    2010-02-12 19:35:45 +0000
+++ b/lisp/ChangeLog    2010-02-13 19:29:25 +0000
@@ -1,3 +1,10 @@
+2010-02-13  Glenn Morris  <address@hidden>
+
+       * simple.el (transpose-subr): Give it a doc-string.
+
+       * textmodes/paragraphs.el (transpose-paragraphs, transpose-sentences):
+       Doc fixes.
+
 2010-02-12  Juri Linkov  <address@hidden>
 
        * arc-mode.el (archive-unique-fname): Make directories for nested

=== modified file 'lisp/simple.el'
--- a/lisp/simple.el    2010-02-04 05:02:56 +0000
+++ b/lisp/simple.el    2010-02-13 19:29:25 +0000
@@ -4854,7 +4854,18 @@
                       (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))

=== modified file 'lisp/textmodes/paragraphs.el'
--- a/lisp/textmodes/paragraphs.el      2010-01-13 08:35:10 +0000
+++ b/lisp/textmodes/paragraphs.el      2010-02-13 19:29:25 +0000
@@ -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 @@
   (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 @@
    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))