From: Tim Vaughan Date: Thu, 12 Dec 2019 11:00:33 +0000 (+0100) Subject: Added some missing docstrings. X-Git-Url: https://thelambdalab.xyz/gitweb/index.cgi?a=commitdiff_plain;h=bc2e732f5d42c26776a282b04483a5f914345ee1;p=emus.git Added some missing docstrings. --- diff --git a/emus.el b/emus.el index 75b92e0..7e2e64e 100644 --- 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