docs: update docstrings

lyrics-fetcher-genius.el

@@ -51,8 +51,12 @@ The flow is at follows:
 3. Fetch lyrics from HTML page of the result
 4. Call CALLBACK with the resulting lyrics string
 
-For TRACK and SYNC arguments, take a look at
+TRACK should be EMMS-compatible alist or string, take a look at
-`lyrics-fetcher--genius-do-query'."
+`lyrics-fetcher--genius-format-query'.  If the search is
+successful, CALLBACK will be called with the result.
+
+If SYNC is non-nil, perform request synchronously and ask the
+user to pick the matching search result."
   (lyrics-fetcher--genius-do-query
    track
    (lambda (data)
@@ -71,8 +75,9 @@ TRACK should be EMMS-compatible alist or string, take a look at
 `lyrics-fetcher--genius-format-query'.  If the search is
 successful, CALLBACK will be called with the result.
 
-If SYNC is non-nil, perform request synchronously and ask the
+SYNC determines whether the request is syncronous.  The parameter
-user to pick the matching search result."
+is useful when it is neccessary to ask user for something right
+after the request."
   (if (string-empty-p lyrics-fetcher-genius-access-token)
       (message "Genius client access token not set!")
     (message "Sending a query to genius API...")
@@ -143,9 +148,7 @@ first song."
 (defun lyrics-fetcher--genius-fetch-lyrics (url callback &optional sync)
   "Fetch lyrics from genius.com page at URL and call CALLBACK with result.
 
-If SYNC is non-nil, the request will be performed synchronously, but
+If SYNC is non-nil, the request will be performed synchronously."
-the function will still make Emacs lag, as HTML parsing is pretty
-expensive."
   (message "Getting lyrics from %s" url)
   (request url
     :parser 'buffer-string
@@ -171,14 +174,16 @@ expensive."
 (defun lyrics-fetcher-genius-download-cover (track callback folder &optional sync)
   "Downloads album cover of TRACK.
 
-Requies `lyrics-fetcher-genius-access-token' to be set.
+Requies `lyrics-fetcher-genius-access-token' to be set and
+imagemagick's \"convert\" to be available in PATH.
 
 TRACK should be EMMS-compatible alist or string, take a look at
 `lyrics-fetcher--genius-format-query'.  If the search is
-successful, CALLBACK will be called with the resulting lyrics
+successful, CALLBACK will be called with the resulting filename of the
-text.
+large cover.
 
-In EMMS, track contains all posible information about the album.
+In EMMS, track contains all posible information about the album, so a
+sample track is used instead of an actual album object.
 
 The file will be saved to FOLDER and will be named
 \"cover_large.<extension>\".
@@ -201,7 +206,7 @@ If SYNC is non-nil, user will be prompted for a matching song."
 The file will be saved to FOLDER and will be named
 \"cover_large.<extension>\".
 
-CALLBACK will be called with a path to the resulting file."
+CALLBACK is passed to `lyrics-fetcher--genius-save-album-url'."
   (request
     (format "https://api.genius.com/songs/%s" id)
     :parser 'json-read
@@ -229,7 +234,7 @@ CALLBACK will be called with the path to the resulting file."
                                      (assoc 'response data)))))))
       (if (not url)
           (message "Album cover not found")
-        (message "Downloading cover image...")
+        (message "Downloading the cover image...")
         (request url
           :encoding 'binary
           :complete

lyrics-fetcher.el

@@ -106,7 +106,6 @@ extensibility."
   :group 'lyrics-fetcher)
 
 ;;; Actual lyrics fetching
-
 (defun lyrics-fetcher-format-song-name (track)
   "Format TRACK to a human-readable form.
 
@@ -180,10 +179,10 @@ one isn’t the one required."
       (message "Error: no track found!")
     (let ((song-name (funcall lyrics-fetcher-format-song-name-method track))
           (file-name (funcall lyrics-fetcher-format-file-name-method track))
-          ;; The function is indented to be called both interactive
+          ;; The function is indented to be called both interactively
-          ;; and via recursion with asyncronous callbacks, during with
+          ;; and via recursion in asyncronous callbacks, during with
           ;; `current-prefix-arg' will be unset. So this is necessary
-          ;; to pass the behavior down the recursion.
+          ;; to pass the behavior down the recursive calls.
           (force-fetch (or force-fetch (member (prefix-numeric-value current-prefix-arg) '(4 16))))
           (sync (or sync (member (prefix-numeric-value current-prefix-arg) '(16)))))
       (if (and (not force-fetch) (lyrics-fetcher--lyrics-saved-p file-name))
@@ -238,7 +237,7 @@ FORCE-FETCH and SYNC are passed to `lyrics-fetcher-show-lyrics'."
           :sync sync))))))
 
 ;;; EMMS integration
-(defun lyrics-fetcher-emms-browser-fetch-at-point ()
+(defun lyrics-fetcher-emms-browser-show-at-point ()
   "Fetch data for the current point in EMMS browser.
 
 If the point contains just one song, it will be fetched the usual way
@@ -246,8 +245,8 @@ via `lyrics-fetcher-show-lyrics'.  Lyrics will be show upon successful
 completion.
 
 If the point contains many songs (e.g. it's an album), the lyrics
-will be fetched consequentially for every song.  Note that the
+will be fetched consequentially for every song.  The process stops at
-process will be stopped at the first failure.
+the first failure.
 
 Behavior of the function is modified by \\[universal-argument]
 the same way as `lyrics-fetcher-show-lyrics'."
@@ -272,6 +271,10 @@ the same way as `lyrics-fetcher-show-lyrics'."
 (defun lyrics-fetcher-emms-browser-fetch-covers-at-point ()
   "Fetch album covers for the current point in EMMS browser.
 
+If the point contains multiple albums, the covers will be fetched
+consequentially for each album.  The process stops at
+the first failure.
+
 Behavior of the function is modified by \\[universal-argument]
 the same way as `lyrics-fetcher-show-lyrics'."
   (interactive)
@@ -284,7 +287,7 @@ the same way as `lyrics-fetcher-show-lyrics'."
 (defun lyrics-fetcher--emms-extract-albums (bdata)
   "Extract a list of sample song alists from each album in BDATA.
 
-One sample song per each album."
+One sample song is given per each album."
   (cond
    ((eq (cdr (assoc 'type bdata)) 'info-album)
     (list (cdadr (assoc 'data (cdadr (assoc 'data bdata))))))
@@ -351,8 +354,6 @@ TRACK is either a string or EMMS alist."
 \\{lyrics-fetcher-view-mode-map}")
 
 ;;; Album cover fetching
-
-
 (cl-defun lyrics-fetcher--fetch-cover-many (tracks &optional &key start force-fetch sync)
   "Fetch album covers for every track in the TRACKS list.