emms-mark, emms-tag-editor: Improve documentation and messages

darcs-hash:20070606020643-1bfb2-fe16b89855d731eb81f486db0c82d3d8d5f46cbc.gz

1 files changed, 36 insertions, 17 deletions

diff --git a/emms-mark.el b/emms-mark.el
index 0eec5f3..5132b1d 100644
--- a/emms-mark.el
+++ b/emms-mark.el
@@ -1,10 +1,9 @@
 ;;; emms-mark.el --- mark track like dired
 
-;; Copyright (C) 2006, 2007 Ye Wenbin
+;; Copyright (C) 2006, 2007 Free Software Foundation, Inc.
 ;;
 ;; Author: Ye Wenbin <wenbinye@163.com>
 ;; Keywords: 
-;; X-URL: not distributed yet
 
 ;; This program is free software; you can redistribute it and/or modify
 ;; it under the terms of the GNU General Public License as published by
@@ -46,7 +45,8 @@
   "Return a description of the current track."
   (assert (not (eq (default-value 'emms-track-description-function)
                    'emms-mark-track-description))
-          nil "Should never set emms-track-selection-function to be emms-mark-track-description.")
+          nil (concat "Do not set `emms-track-selection-function' to be"
+                      " emms-mark-track-description."))
   (concat "  " (funcall (default-value 'emms-track-description-function)
                         track)))
 
@@ -66,6 +66,9 @@
     (?\040 . emms-playlist-track-face)))
 
 (defun emms-mark-track (&optional arg)
+  "Mark the current track.
+If ARG is positive, also mark the next ARG-1 tracks as well.
+If ARG is negative, also mark the previous ARG-1 tracks."
   (interactive "p")
   (or arg (setq arg 1))
   (let ((face (assoc-default emms-mark-char emms-mark-face-alist))
@@ -95,38 +98,47 @@
                     (1+ arg)))))))
 
 (defun emms-mark-unmark-track (&optional arg)
+  "Unmark the current track.
+If ARG is positive, also unmark the next ARG-1 tracks as well.
+If ARG is negative, also unmark the previous ARG-1 tracks."
   (interactive "p")
   (let ((emms-mark-char ?\040))
     (emms-mark-track arg)))
 
 (defun emms-mark-forward (arg)
+  "Mark one or more tracks and move the point past the newly-marked tracks.
+See `emms-mark-track' for further details."
   (interactive "p")
   (emms-mark-track arg)
   (forward-line arg))
 
 (defun emms-mark-unmark-forward (arg)
+  "Unmark one or more tracks and move the point past the tracks.
+See `emms-mark-unmark-track' for further details."
   (interactive "p")
   (emms-mark-unmark-track arg)
   (forward-line arg))
 
 (defun emms-mark-all ()
+  "Mark all tracks in the current buffer."
   (interactive)
   (save-excursion
     (goto-char (point-min))
     (emms-mark-track (count-lines (point-min) (point-max)))))
 
 (defun emms-mark-unmark-all ()
+  "Unmark all tracks in the current buffer."
   (interactive)
   (emms-mark-do-with-marked-track 'emms-mark-unmark-track))
 
 (defun emms-mark-regexp (regexp arg)
-  "Mark all tracks matching a regexp. A prefix argument means to
+  "Mark all tracks matching REGEXP. A prefix argument means to
 unmark them instead."
   (interactive
    (list
     (read-from-minibuffer (if current-prefix-arg
-                              "Mark track match: "
-                            "Unmark track match: "))
+                              "Mark tracks matching: "
+                            "Unmark tracks matching: "))
     current-prefix-arg))
   (let ((emms-mark-char (if arg ?\040 ?*)))
     (save-excursion
@@ -136,6 +148,7 @@ unmark them instead."
         (forward-line 1)))))
 
 (defun emms-mark-toggle ()
+  "Toggle all marks in the current buffer."
   (interactive)
   (save-excursion
     (goto-char (point-min))
@@ -147,7 +160,7 @@ unmark them instead."
         (forward-line 1)))))
 
 (defsubst emms-mark-has-markedp ()
-  "Predicate whether the playlist has marked line"
+  "Return non-nil if the playlist has a marked line, nil otherwise."
   (save-excursion
     (goto-char (point-min))
     (re-search-forward (format "^[%c]" emms-mark-char) nil t)))
@@ -156,13 +169,15 @@ unmark them instead."
 
 ;;{{{ functions to operate marked tracks
 (defun emms-mark-do-with-marked-track (func &optional move)
-  "Call FUNC on every marked line in current playlist. The FUNC take
-no argument, so if need the track in marked line, should use
-`emms-playlist-track-at' to get it. The FUNC can also modify the
-playlist buffer, such as delete the line. It is import for who want to
-use this function, this function didn't move forward. So if FUNC don't
-move forward, set the second parameter MOVE to non-nil. Otherwise, the
-function will never exit the loop."
+  "Call FUNC on every marked line in current playlist.
+The function specified by FUNC takes no argument, so if the track
+on the marked line is needed, use `emms-playlist-track-at' to get
+it.
+
+The function can also modify the playlist buffer, such as
+deleting the current line.  If the function doesn't move forward,
+be sure to set the second parameter MOVE to non-nil.  Otherwise
+the function will never exit the loop."
   (let ((regexp (format "^[%c]" emms-mark-char))
         (newfunc func))
     (if move
@@ -175,8 +190,8 @@ function will never exit the loop."
 
 (defun emms-mark-mapcar-marked-track (func &optional move)
   "This function does the same thing as
-`emms-mark-do-with-marked-track', the only difference is this function
-collect the result of FUNC."
+`emms-mark-do-with-marked-track', the only difference being that
+this function collects the result of FUNC."
   (let ((regexp (format "^[%c]" emms-mark-char))
         result (newfunc func))
     (if move
@@ -190,6 +205,7 @@ collect the result of FUNC."
       (nreverse result))))
 
 (defun emms-mark-delete-marked-tracks ()
+  "Delete all tracks that have been marked in the current buffer."
   (interactive)
   (emms-with-inhibit-read-only-t
    (emms-mark-do-with-marked-track
@@ -197,6 +213,7 @@ collect the result of FUNC."
                                (progn (forward-line 1) (point)))))))
 
 (defun emms-mark-kill-marked-tracks ()
+  "Kill all tracks that have been marked in the current buffer."
   (interactive)
   (let (tracks buffer-read-only)
     (emms-mark-do-with-marked-track
@@ -208,6 +225,7 @@ collect the result of FUNC."
     (kill-new tracks)))
 
 (defun emms-mark-copy-marked-tracks ()
+  "Copy all tracks that have been marked in the current buffer."
   (interactive)
   (let (tracks)
     (emms-mark-do-with-marked-track
@@ -230,7 +248,8 @@ collect the result of FUNC."
     (define-key map "U" 'emms-mark-unmark-all)
     (define-key map "t" 'emms-mark-toggle)
     (define-key map "%m" 'emms-mark-regexp)
-    map))
+    map)
+  "Keymap for `emms-mark-mode'.")
 
 (defun emms-mark-mode ()
   "An EMMS major mode that allows tracks to be marked like dired.