Document move-dup functions and remove interactivity for duplicate-line and duplicate-region

wyuenho · wyuenho · commit 118ecba74332 · 2014-06-12T20:50:09.000+08:00
diff --git a/move-dup.el b/move-dup.el
@@ -16,16 +16,17 @@
 ;; this program.  If not, see <http://www.gnu.org/licenses/>.
 
 ;; Author: Jimmy Yuen Ho Wong <wyuenho@gmail.com>
-;; Version: 0.1.2
-;; Created 11 June 2014
+;; Version: 0.1.3
+;; Created: 11 June 2014
 ;; Keywords: convenience wp
 
 ;; This file is not part of GNU Emacs.
 
 ;;; Commentary:
 
 ;; This package offers convenient editing commands much like Eclipse's ability
-;; to move and duplicate lines or rectangular selections.
+;; to move and duplicate lines or rectangular selections by way of
+;; `move-dup-mode'.
 
 ;; If you aren't using `package.el' or plan to customize the default
 ;; key-bindings, you need to put `move-dup.el' into your Emacs' load-path and
@@ -34,7 +35,7 @@
 ;; (require 'move-dup)
 
 ;; If you don't want to toggle the minor mode, you can bind these functions like
-;; so. All of these functions work on a single line or a rectangle.
+;; so.  All of these functions work on a single line or a rectangle.
 
 ;; (global-set-key (kbd "M-<up>") 'md/move-lines-up)
 ;; (global-set-key (kbd "M-<down>") 'md/move-lines-down)
@@ -43,13 +44,19 @@
 
 ;; If you used `package.el' to install `move-dup.el', this is equivalent to all
 ;; of the above.
-;; (global-move-dup-minor-mode)
+;; (global-move-dup-mode)
 
-;; You can also turn on `move-dup-minor-mode' individually for each buffer.
-;; (move-dup-minor-mode)
+;; You can also turn on `move-dup-mode' individually for each buffer.
+;; (move-dup-mode)
 
 ;;; Code:
 (defun md/ensure-rectangle ()
+  "Normalizes the selection by making sure it's always a rectangle.
+
+After normalization, the point always comes after mark.  The
+region will always be expanded such that it will always begin
+from the beginning of the line the mark is on, and ends at the
+beginning of the next line of the end of the region."
   (if (< (point) (mark))
       (exchange-point-and-mark))
   (when (not (char-equal (char-before (region-end)) 10))
@@ -60,7 +67,14 @@
   (exchange-point-and-mark))
 
 (defun md/move-region (&optional n)
-  (interactive "p")
+  "Interactive function to move the currect selection N lines.
+
+If the selection is not a rectangle, this function will expand
+the selection to a rectangle via the
+function `(ensure-rectangle)` and move it accordingly.  If the
+prefix N is positive, this function moves the rectangle forward N
+lines; otherwise backward."
+  (interactive "*p")
   (md/ensure-rectangle)
   (let* ((start (region-beginning))
          (end (region-end))
@@ -80,41 +94,69 @@
       (exchange-point-and-mark))))
 
 (defun md/move-line (&optional n)
-  (interactive "p")
+  "Interactive function to move the current line N line.
+
+If the prefix N is positive, this function moves the current line
+forward N lines; otherwise backward."
+  (interactive "*p")
   (let ((col (current-column)))
     (forward-line 1)
     (transpose-lines n)
     (forward-line -1)
     (move-to-column col)))
 
 (defun md/move-line-or-region (n)
+  "Decides whether a line or selection should be moved N lines."
   (if (use-region-p)
       (md/move-region n)
     (md/move-line n)))
 
 (defun md/move-lines-up (&optional n)
-  (interactive "p")
+  "Interactive function to move the current line or selection up.
+
+If the prefix N is positive, this function moves the current line
+or selection up N lines; otherwise down."
+  (interactive "*p")
   (md/move-line-or-region (if (or (null n) (= n 0)) -1 (- n))))
 
 (defun md/move-lines-down (&optional n)
-  (interactive "p")
+  "Interactive function to move the current line or selection down.
+
+If the prefix N is positive, this function moves the current line
+or selection down N lines; otherwise up."
+  (interactive "*p")
   (md/move-line-or-region (if (or (null n) (= n 0)) 1 n)))
 
-(defun md/duplicate-up (&optional times)
-  (interactive "p")
-  (dotimes (i times) (md/duplicate-line-or-region "up")))
+(defun md/duplicate-up (&optional n)
+  "Interactive function to duplicate the current line or selection upward.
+
+If the prefix N is positive, this function makes N duplicates of
+the current line or selection and place them above the current
+line or selection."
+  (interactive "*p")
+  (dotimes (i n) (md/duplicate-line-or-region "up")))
+
+(defun md/duplicate-down (&optional n)
+  "Interactive function to duplicate the current line or selection downward.
 
-(defun md/duplicate-down (&optional times)
-  (interactive "p")
-  (dotimes (i times) (md/duplicate-line-or-region "down")))
+If the prefix N is positive, this function makes N duplicates of
+the current line or selection and place them below the current
+line or selection."
+  (interactive "*p")
+  (dotimes (i n) (md/duplicate-line-or-region "down")))
 
 (defun md/duplicate-line-or-region (direction)
+  "Decides whether a line or selection should be duplicated.
+
+DIRECTION must be one of \"up\" or \"down\"."
   (if (use-region-p)
       (md/duplicate-region direction)
     (md/duplicate-line direction)))
 
 (defun md/duplicate-line (direction)
-  (interactive "p")
+  "Function to duplicate the current line.
+
+DIRECTION must be one of \"up\" or \"down\"."
   (let ((text (buffer-substring (line-beginning-position) (line-end-position)))
         (col (current-column)))
     (forward-line)
@@ -125,7 +167,16 @@
     (move-to-column col)))
 
 (defun md/duplicate-region (direction)
-  (interactive "p")
+  "Function to duplicate the current selection.
+
+DIRECTION must be one of \"up\" or \"down\".
+
+If the selection is not a rectangle, this function will expand
+the selection to a rectangle via the
+function `(ensure-rectangle)` and duplicate it accordingly.  If
+the DIRECTION is \"up\", this function duplicates the selected
+rectangle and places it __below__ the selection; __above__ if
+DIRECTION is \"down\"."
   (md/ensure-rectangle)
   (let* ((start (region-beginning))
          (end (region-end))
@@ -149,14 +200,23 @@
 
 ;;;###autoload
 (define-minor-mode move-dup-mode
-  "Eclipse-like moving and duplicating lines or rectangles with default key-bindings."
+  "Eclipse-like moving and duplicating lines or rectangles with
+default key bindings.
+
+The default key bindings are:
+
+\([M-up] . md/move-lines-up)
+\([M-down] . md/move-lines-down)
+\([C-M-up] . md/duplicate-up)
+\([C-M-down] . md/duplicate-down)"
   :lighter " md"
   :keymap '(([M-up] . md/move-lines-up)
             ([M-down] . md/move-lines-down)
             ([C-M-up] . md/duplicate-up)
             ([C-M-down] . md/duplicate-down)))
 
 (defun move-dup-on ()
+  "Decides whether the function `move-dup-mode' should be called with t."
   (unless (minibufferp)
     (move-dup-mode 1)))
 
