Added remaining docstrings. Flycheck now happy.

diff --git a/emus.el b/emus.el
index 7e2e64e..12c57f1 100644 (file)
--- a/emus.el
+++ b/emus.el
@@ -76,13 +76,33 @@
   '((t :inherit bold))
   "Face used for current track cursor")
 
-;;; mpg123 process
-;;
+
+;;; Global variables
 
 (defvar emus--proc-in-use nil
   "If non-nil, disables `emus-send-cmd'.
 Used to prevent commands from interfering with library construction.")
 
+(defvar emus-tracks nil
+  "Emus audio library.")
+
+(defvar emus-current-track nil
+  "Currently-selected emus track.")
+
+(defvar emus-state 'stopped
+  "Current playback state.")
+
+(defvar emus-continuous-playback t
+  "If non-nil, emus will automatically play the next track when the current track is finished.")
+
+(defvar emus-current-volume 100
+  "The current playback volume.")
+
+
+;;; mpg123 process
+;;
+
+
 (defun emus-get-process ()
   "Return current or new mpg123 process."
   (let* ((emus-process-raw (get-process "emus-process"))
@@ -123,9 +143,6 @@ be used by `emus--load-library'."
   "Get all mp3 files in main emus directory."
   (directory-files-recursively emus-directory ".*\\.mp3"))
 
-(defvar emus-tracks nil
-  "Emus audio library.")
-
 (defun emus-make-track (artist album title filename &optional pos)
   "Create an object representing an emus track.
 ARTIST, ALBUM and TITLE are used to describe the track, FILENAME
@@ -229,10 +246,6 @@ by the filesystem."
 ;;; Playback
 ;;
 
-(defvar emus-current-track nil)
-(defvar emus-state 'stopped)
-(defvar emus-continuous-playback t)
-
 (defun emus--suspend-cp ()
   "Suspend continuous playback."
   (setq emus-continuous-playback nil))
@@ -293,9 +306,6 @@ If the track is currently paused, resume playback."
        (unless (eq emus-state 'paused)))
      (emus--update-track emus-current-track))))
 
-(defvar emus-current-volume 100
-  "The current playback volume.")
-
 (defun emus-set-volume (pct)
   "Set the playback volume to PCT %."
   (emus--with-library
@@ -411,6 +421,13 @@ If PREV is non-nil, plays the last track of the previous album."
 ;;
 
 (defun emus--insert-track (track &optional prev-track first)
+  "Insert a button representing TRACK into the current buffer.
+
+When provided, PREV-TRACK is used to determine whether to insert additional
+headers representing the artist or the album title.
+
+If non-nil, FIRST indicates that the track is the first in the library
+and thus requires both artist and album headers."
   (let* ((artist (emus-track-artist track))
          (album (emus-track-album track))
          (title (emus-track-title track))
@@ -458,6 +475,8 @@ If PREV is non-nil, plays the last track of the previous album."
                                   'emus-track))))))
 
 (defun emus--update-track (track)
+  "Rerender entry for TRACK in emus browser buffer.
+Used to update browser display when `emus-current-track' and/or `emus-state' changes."
   (let ((track-pos (emus-track-browser-pos track)))
     (when (and (get-buffer "*emus*")
                (emus-track-browser-pos track))
@@ -472,6 +491,7 @@ If PREV is non-nil, plays the last track of the previous album."
           (goto-char old-point))))))
 
 (defun emus--render-tracks ()
+  "Render all library tracks in emus browser buffer."
   (with-current-buffer "*emus*"
     (let ((inhibit-read-only t)
           (old-pos (point)))
@@ -484,15 +504,17 @@ If PREV is non-nil, plays the last track of the previous album."
       (goto-char old-pos))))
 
 (defun emus--click-track (button)
+  "Begin playback of track indicated by BUTTON."
   (emus-play-track (button-get button 'emus-track))
   (emus-display-status))
 
 (defun emus-centre-current ()
+  "Centre the current track in the browser buffer, if available."
   (interactive)
   (when (get-buffer "*emus*")
-    (when emus-current-track
-      (goto-char (emus-track-browser-pos emus-current-track))
-      (recenter))))
+      (when emus-current-track
+        (goto-char (emus-track-browser-pos emus-current-track))
+        (recenter))))
 
 (defun emus-browse ()
   "Switch to *emus* audio library browser."
@@ -504,24 +526,84 @@ If PREV is non-nil, plays the last track of the previous album."
    (emus-centre-current)))
 
 (defun emus-refresh ()
+  "Refresh the emus library."
   (interactive)
   (emus-stop)
   (setq emus-tracks nil)
   (emus-browse))
 
-(defun emus-playpause-status () (interactive) (emus-playpause) (emus-display-status))
-(defun emus-stop-status () (interactive) (emus-stop) (emus-display-status))
-(defun emus-volume-up-status () (interactive) (emus-volume-up) (emus-display-status))
-(defun emus-volume-down-status () (interactive) (emus-volume-down) (emus-display-status))
-(defun emus-play-next-status () (interactive) (emus-play-next) (emus-display-status))
-(defun emus-play-prev-status () (interactive) (emus-play-prev) (emus-display-status))
-(defun emus-play-next-album-status () (interactive) (emus-play-next-album) (emus-display-status))
-(defun emus-play-prev-album-status () (interactive) (emus-play-prev-album) (emus-display-status))
-(defun emus-jump-10s-forward-status () (interactive) (emus-jump-10s-forward) (emus-display-status))
-(defun emus-jump-10s-backward-status () (interactive) (emus-jump-10s-backward) (emus-display-status))
-(defun emus-centre-current-status () (interactive) (emus-centre-current) (emus-display-status))
+
+;;; Playback + status display commands
+;;
+
+(defun emus-playpause-status ()
+  "Start, pause or resume playback, then display the emus status in the minibuffer."
+  (interactive)
+  (emus-playpause)
+  (emus-display-status))
+
+(defun emus-stop-status ()
+  "Stop playback, then display the emus status in the minibuffer."
+  (interactive)
+  (emus-stop)
+  (emus-display-status))
+
+(defun emus-volume-up-status ()
+  "Increase volume by 10%, then display the emus status in the minibuffer."
+  (interactive)
+  (emus-volume-up)
+  (emus-display-status))
+
+(defun emus-volume-down-status ()
+  "Decrease volume by 10%, then display the emus status in the minibuffer."
+  (interactive)
+  (emus-volume-down)
+  (emus-display-status))
+
+(defun emus-play-next-status ()
+  "Play next track, then display the emus status in the minibuffer."
+  (interactive)
+  (emus-play-next)
+  (emus-display-status))
+
+(defun emus-play-prev-status ()
+  "Play previous track, then display the emus status in the minibuffer."
+  (interactive)
+  (emus-play-prev)
+  (emus-display-status))
+
+(defun emus-play-next-album-status ()
+  "Play first track of next album, then display the emus status in the minibuffer."
+  (interactive)
+  (emus-play-next-album)
+  (emus-display-status))
+
+(defun emus-play-prev-album-status ()
+  "Play last track of previous album, then display the emus status in the minibuffer."
+  (interactive)
+  (emus-play-prev-album)
+  (emus-display-status))
+
+(defun emus-jump-10s-forward-status ()
+  "Jump 10s forward in current track, then display the emus status in the minibuffer."
+  (interactive)
+  (emus-jump-10s-forward)
+  (emus-display-status))
+
+(defun emus-jump-10s-backward-status ()
+  "Jump 10s backward in current track, then display the emus status in the minibuffer."
+  (interactive)
+  (emus-jump-10s-backward)
+  (emus-display-status))
+
+(defun emus-centre-current-status ()
+  "Jump 10s backward in current track, then display the emus status in the minibuffer."
+  (interactive)
+  (emus-centre-current)
+  (emus-display-status))
 
 (defun emus-refresh-status ()
+  "Refresh the emus library, then display the emus status in the minibuffer."
   (interactive)
   (emus-stop)
   (setq emus-tracks nil)
@@ -560,7 +642,7 @@ If PREV is non-nil, plays the last track of the previous album."
                         (kbd ".") 'emus-jump-10s-forward-status
                         (kbd "c") 'emus-centre-current-status))
     map)
-  "Keymap for emus.")
+  "Keymap for emus browser.")
 
 (define-derived-mode emus-browser-mode special-mode "emus-browser"
   "Major mode for EMUS music player file browser.")