From 8c3df2bbe0c81b170f1ab1a0b26dd78c7e1b992c Mon Sep 17 00:00:00 2001 From: SqrtMinusOne Date: Sat, 7 Aug 2021 12:44:56 +0300 Subject: [PATCH] docs: update docstrings --- lyrics-fetcher-genius.el | 31 ++++++++++++++++++------------- lyrics-fetcher.el | 21 +++++++++++---------- 2 files changed, 29 insertions(+), 23 deletions(-) diff --git a/lyrics-fetcher-genius.el b/lyrics-fetcher-genius.el index 021421a..ca0a0ce 100644 --- a/lyrics-fetcher-genius.el +++ b/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 -`lyrics-fetcher--genius-do-query'." +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 +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 -user to pick the matching search result." +SYNC determines whether the request is syncronous. The parameter +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 -the function will still make Emacs lag, as HTML parsing is pretty -expensive." +If SYNC is non-nil, the request will be performed synchronously." (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 -text. +successful, CALLBACK will be called with the resulting filename of the +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.\". @@ -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.\". -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 diff --git a/lyrics-fetcher.el b/lyrics-fetcher.el index 6b25d95..0944bb6 100644 --- a/lyrics-fetcher.el +++ b/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 - ;; and via recursion with asyncronous callbacks, during with + ;; The function is indented to be called both interactively + ;; 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 -process will be stopped at the first failure. +will be fetched consequentially for every song. The process stops at +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.