Then they left without a sound

[musicbrainz.git] / listenbrainz.el

diff --git a/listenbrainz.el b/listenbrainz.el
index 02295510799734814ec4c8aa34e704b13c9fc356..43084f7773ea41bcb06eea5c6e87ba220cb9d0e3 100644 (file)
--- a/listenbrainz.el
+++ b/listenbrainz.el
@@ -27,10 +27,19 @@
 
 ;;; Commentary:
 
-;; - listen & submit metadata to ListenBrainz
-;; - partial & incomplete
-;; - no error checks
-;; - sync -> async
+;; An interface to ListenBrainz, a project to store a record of the music that
+;; you listen to. The listening data, can be used to provide statistics,
+;; recommendations and general exploration.
+;;
+;; The package can be used programmatically (e.g. from a music player) to auto
+;; submit listening data `listenbrainz-submit-listen'. There are other entrypoints
+;; for reading user stats such as `listenbrainz-stats-artists' or
+;; `listenbrainz-listens'.
+;;
+;; Some API calls require a user token, which can be found in your ListenBrainz
+;; profile. Configure, set or `customize' the `listenbrainz-api-token' as needed.
+;;
+;; https://listenbrainz.readthedocs.io/
 
 
 ;;; Code:
@@ -104,7 +113,6 @@ All timestamps used in ListenBrainz are UNIX epoch timestamps in UTC."
 ;;
 ;;;; ; ;; ;
 
-
 (defmacro listenbrainz--deformatter (name format-string format-args alist)
   "Generate function with NAME to format data returned from an API call.
 The function has the name `listenbrainz--format-NAME`.
@@ -216,7 +224,6 @@ macroexpands to something like ->
 ;;
 ;;; ; ;; ; ;   ;
 
-;;;###autoload
 (defun listenbrainz-validate-token (token)
   "Check if TOKEN is valid. Return a username or nil."
   (message "listenbrainz: checking token %s" token)
@@ -255,7 +262,8 @@ macroexpands to something like ->
              :sync t
              :success (cl-function
                        (lambda (&key data &allow-other-keys)
-                         (message "Listens for user: %s" username)))))))
+                         (message "Listens for user: %s\n%s" username
+                                  (if data data ""))))))))
     (princ (listenbrainz--format-listens response))))
 
 
@@ -272,7 +280,8 @@ macroexpands to something like ->
              :sync t
              :success (cl-function
                        (lambda (&key data &allow-other-keys)
-                         (message "User playing now: %s" username)))))))
+                         (message "User playing now: %s\n%s" username
+                                  (if data data ""))))))))
     (princ (listenbrainz--format-playing response))))
 
 
@@ -351,7 +360,8 @@ possible values are week, month, year, all_time, defaults to all_time."
              :sync t
              :success (cl-function
                        (lambda (&key data &allow-other-keys)
-                         (message "Top recordings for user: %s" username)))))))
+                         (message "Top recordings for user: %s\n%s" username
+                                  (if data data ""))))))))
     (princ (listenbrainz--format-stats-2 response))))
 
 
@@ -374,7 +384,8 @@ possible values are week, month, year, all_time, defaults to all_time."
              :sync t
              :success (cl-function
                        (lambda (&key data &allow-other-keys)
-                         (message "Top releases for user: %s" username)))))))
+                         (message "Top releases for user: %s\n%s" username
+                                  (if data data ""))))))))
     (princ (listenbrainz--format-stats-0 response))))
 
 
@@ -397,7 +408,8 @@ possible values are week, month, year, all_time, defaults to all_time."
              :sync t
              :success (cl-function
                        (lambda (&key data &allow-other-keys)
-                         (message "Top artists for user: %s" username)))))))
+                         (message "Top artists for user: %s\n%s" username
+                                  (if data data ""))))))))
     (princ (listenbrainz--format-stats-1 response))))
 
 
@@ -423,10 +435,11 @@ OUTPUT format can be either `list' (default) or `graph'."
              :sync t
              :success (cl-function
                        (lambda (&key data &allow-other-keys)
-                         (message "Followers for %s" username)))))))
+                         (message "Followers for %s\n%s" username
+                                  (if data data ""))))))))
     (if (string= "graph" output)
-         (princ (listenbrainz--format-followers-graph response))
-         (princ (listenbrainz--format-followers-list response)))))
+        (princ (listenbrainz--format-followers-graph response))
+        (princ (listenbrainz--format-followers-list response)))))
 
 ;;;###autoload
 (defun listenbrainz-following (username)
@@ -441,7 +454,8 @@ OUTPUT format can be either `list' (default) or `graph'."
              :sync t
              :success (cl-function
                        (lambda (&key data &allow-other-keys)
-                         (message "Users %s is following" username)))))))
+                         (message "Users %s is following\n%s" username
+                                  (if data data ""))))))))
     (princ (listenbrainz--format-following response))))