Added some missing docstrings.

diff --git a/emus.el b/emus.el
index 75b92e0..7e2e64e 100644 (file)
--- a/emus.el
+++ b/emus.el
@@ -79,7 +79,9 @@
 ;;; mpg123 process
 ;;
 
-(defvar emus--proc-in-use nil)
+(defvar emus--proc-in-use nil
+  "If non-nil, disables `emus-send-cmd'.
+Used to prevent commands from interfering with library construction.")
 
 (defun emus-get-process ()
   "Return current or new mpg123 process."
@@ -100,12 +102,16 @@
         proc))))
 
 (defun emus--send-cmd-raw (cmd &rest args)
+  "Send a command CMD with args ARGS to the mpg123 process.
+This procedure does not respect `emus--proc-in-use' and thus should only
+be used by `emus--load-library'."
     (process-send-string (emus-get-process)
                          (concat
                           (seq-reduce (lambda (s1 s2) (concat s1 " " s2)) args cmd)
                           "\n")))
 
 (defun emus-send-cmd (cmd &rest args)
+  "Send a command CMD with args ARGS to the mpg123 process."
   (unless emus--proc-in-use
     (apply #'emus--send-cmd-raw cmd args)))
 
@@ -121,27 +127,40 @@
   "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
+refers to the mp3 file containing the track.  If non-nil, POS
+specifies the position of the record representing this track in the
+emus browser buffer."
   (vector artist album title filename pos))
 
 (defun emus-track-artist (track)
+  "The artist corresponding to TRACK."
   (elt track 0))
 
 (defun emus-track-album (track)
+  "The album corresponding to TRACK."
   (elt track 1))
 
 (defun emus-track-title (track)
+  "The title of TRACK."
   (elt track 2))
 
 (defun emus-track-file (track)
+  "The mp3 file corresponding to TRACK."
   (elt track 3))
 
 (defun emus-track-browser-pos (track)
+  "The location of the browser buffer record corresponding to TRACK."
   (elt track 4))
 
 (defun emus-set-track-browser-pos (track pos)
+  "Set the location of the browser buffer record corresponding to TRACK to POS."
   (aset track 4 pos))
 
 (defun emus--load-library (then)
+  "Initialize the emus track library.
+Once the library is initialized, the function THEN is called."
   (unless emus--proc-in-use
     (setq emus--proc-in-use t)
     (emus--suspend-cp)
@@ -171,6 +190,7 @@
       (emus--send-cmd-raw "lp" (car filenames)))))
 
 (defun emus--make-track-from-tagstr (filename tagstr)
+  "Parse TAGSTR to populate the fields of a track corresponding to FILENAME."
   (let ((artist "")
         (album "")
         (title ""))
@@ -185,6 +205,9 @@
     (emus-make-track artist album title filename nil)))
 
 (defun emus--sort-tracks ()
+  "Sort the library tracks according to artist and album.
+Leaves the track titles unsorted, so they will appear in the order specified
+by the filesystem."
   (sort emus-tracks
         (lambda (r1 r2)
           (let ((artist1 (emus-track-artist r1))
@@ -195,11 +218,12 @@
                   (string< album1 album2))
               (string< artist1 artist2))))))
 
-(defmacro emus--with-library (&rest args)
+(defmacro emus--with-library (&rest body)
+  "Evaluate BODY with the library initialized."
   `(if emus-tracks
-       (progn ,@args)
+       (progn ,@body)
      (emus--load-library
-      (lambda () ,@args))))
+      (lambda () ,@body))))
 
 
 ;;; Playback
@@ -210,12 +234,14 @@
 (defvar emus-continuous-playback t)
 
 (defun emus--suspend-cp ()
+  "Suspend continuous playback."
   (setq emus-continuous-playback nil))
 
 (defun emus--resume-cp ()
+  "Resume continuous playback."
   (setq emus-continuous-playback t)
   (set-process-filter (emus-get-process)
-                      (lambda (proc string)
+                      (lambda (_proc string)
                         (and emus-continuous-playback
                              (eq emus-state 'playing)
                              (string-suffix-p "@P 0\n" string)
@@ -252,6 +278,9 @@
    (emus-send-cmd "s")))
 
 (defun emus-playpause ()
+  "Begin playback of the current track.
+If the track is already playing, pause playback.
+If the track is currently paused, resume playback."
   (interactive)
   (emus--with-library
    (when emus-current-track
@@ -264,25 +293,31 @@
        (unless (eq emus-state 'paused)))
      (emus--update-track emus-current-track))))
 
-(defvar emus-current-volume 100)
+(defvar emus-current-volume 100
+  "The current playback volume.")
 
 (defun emus-set-volume (pct)
+  "Set the playback volume to PCT %."
   (emus--with-library
    (setq emus-current-volume pct)
    (emus-send-cmd "v" (number-to-string pct))))
 
 (defun emus-volume-increase-by (delta)
+  "Increase the playback volume by DELTA %."
   (emus-set-volume (max 0 (min 100 (+ emus-current-volume delta)))))
 
 (defun emus-volume-up ()
+  "Increase the playback volume by 10%."
   (interactive)
   (emus-volume-increase-by 10))
 
 (defun emus-volume-down ()
+  "Decrease the playback volume by 10%."
   (interactive)
   (emus-volume-increase-by -10))
 
 (defun emus--play-adjacent-track (&optional prev)
+  "Play the next track in the library, or the previous if PREV is non-nil."
   (emus--with-library
    (let ((idx (seq-position emus-tracks emus-current-track))
          (offset (if prev -1 +1)))
@@ -296,6 +331,8 @@
        (error "No track selected")))))
 
 (defun emus--play-adjacent-album (&optional prev)
+  "Play the first track of the next album in the library.
+If PREV is non-nil, plays the last track of the previous album."
   (emus--with-library
    (let ((idx (seq-position emus-tracks emus-current-track)))
      (if idx
@@ -317,18 +354,22 @@
        (error "No track selected")))))
 
 (defun emus-play-next ()
+  "Play the next track in the library."
   (interactive)
   (emus--play-adjacent-track))
 
 (defun emus-play-prev ()
+  "Play the previous track in the library."
   (interactive)
   (emus--play-adjacent-track t))
 
 (defun emus-play-next-album ()
+  "Play the first track of the next album in the library."
   (interactive)
   (emus--play-adjacent-album))
 
 (defun emus-play-prev-album ()
+  "Play the last track of the previous album in the library."
   (interactive)
   (emus--play-adjacent-album t))
 
@@ -348,6 +389,7 @@
   (emus-jump -10))
 
 (defun emus-display-status ()
+  "Display the current playback status in the minibuffer."
   (interactive)
   (emus--with-library
    (message