From fc29823e5058d7ba70e95762f6d2f5f7b27ca5cc Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Fri, 18 Oct 2024 08:52:02 +0300 Subject: [PATCH] ; Fix documentation of recent changes in mpc.el * etc/NEWS: Fix entry for 'mpc-notifications'. * lisp/mpc.el (mpc-status-callbacks, mpc-format) (mpc-cover-image-find, mpc-cover-image-p, mpc-notifications) (mpc-notifications-title, mpc-notifications-body): Doc fixes. (cherry picked from commit 09e586b38352e1661ef96a47b89d835f0ff30bd2) --- etc/NEWS | 8 +++++--- lisp/mpc.el | 24 ++++++++++++------------ 2 files changed, 17 insertions(+), 15 deletions(-) diff --git a/etc/NEWS b/etc/NEWS index 303d4aee4b0..ece62d563af 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -495,9 +495,11 @@ or behaves like 'widen' if not in a fold. --- *** New user option 'mpc-notifications'. -When non-nil MPC displays a desktop notification when the song changes. -The notification’s title and body can be customized with -'mpc-notifications-title' and 'mpc-notifications-body'. +When non-nil, MPC (the Emacs front-end to Music Player Daemon) displays +a desktop notification when the song changes, using +'notifications-notify'. The notification's title and body can be +customized using the new user options 'mpc-notifications-title' and +'mpc-notifications-body'. * New Modes and Packages in Emacs 31.1 diff --git a/lisp/mpc.el b/lisp/mpc.el index e754b1e9a50..ea472751832 100644 --- a/lisp/mpc.el +++ b/lisp/mpc.el @@ -465,8 +465,8 @@ which will be concatenated with proper quoting before passing them to MPD." (t . mpc-current-refresh)) "Alist associating properties to the functions that care about them. Each entry has the form (PROP . FUN) to call FUN (without arguments) -whenever property PROP changes. PROP can be t to mean -to call FUN for any change whatsoever.") +whenever property PROP changes. PROP can be t, which means to call +FUN for any change whatsoever.") (defun mpc--status-callback () (let ((old-status mpc-status)) @@ -987,11 +987,11 @@ If PLAYLIST is t or nil or missing, use the main playlist." FORMAT-SPEC is a string that includes elements of the form '%-WIDTH{NAME-POST}' that get expanded to the value of -property NAME, +property NAME. The first '-', WIDTH, and -POST are optional. % followed by the optional '-' means to right align the output. -WIDTH limits the output to the specified number of characters by replacing -any further output with a horizontal ellipsis. +WIDTH limits the output to the specified number of characters by +replacing any further output with a horizontal ellipsis. The optional -POST means to use the empty string if NAME is absent or else use the concatenation of the content of NAME with the string POST." @@ -1121,7 +1121,7 @@ string POST." (put-text-property start (point) 'mpc--uptodate-p pred))) (defun mpc-cover-image-find (file) - "Find cover image for FILE." + "Find cover image for FILE in suitable MPC directory." (when-let* ((default-directory mpc-mpd-music-directory) (dir (mpc-file-local-copy (file-name-directory file))) (files (directory-files dir)) @@ -1129,7 +1129,7 @@ string POST." (expand-file-name cover dir))) (defun mpc-cover-image-p (file) - "Check if FILE is a cover image." + "Check if FILE is a cover image suitable for MPC." (let ((covers '(".folder.png" "folder.png" "cover.jpg" "folder.jpg"))) (or (member-ignore-case file covers) (and mpc-cover-image-re (string-match-p mpc-cover-image-re file))))) @@ -2783,7 +2783,7 @@ If stopped, start playback." (declare-function notifications-notify "notifications") (defcustom mpc-notifications nil - "Non-nil means to display notifications when the song changes." + "Non-nil means MPC should display notifications when the song changes." :version "31.1" :type 'boolean) @@ -2791,8 +2791,8 @@ If stopped, start playback." '("%{Title}" "Unknown Title") "List of FORMAT-SPECs used in the notification title. -The first element that expands to a non-empty string is used. -See `mpc-format' for the definition of FORMAT-SPEC." +The first element in the list that expands to a non-empty string +will be used. See `mpc-format' for the definition of FORMAT-SPEC." :version "31.1" :type '(repeat string)) @@ -2800,8 +2800,8 @@ See `mpc-format' for the definition of FORMAT-SPEC." '("%{Artist}" "%{AlbumArtist}" "Unknown Artist") "List of FORMAT-SPEC used in the notification body. -The first element that returns a non-emtpy string is used. -See `mpc-format' for the definition of FORMAT-SPEC." +The first element in the list that expands to a non-empty string +will be used. See `mpc-format' for the definition of FORMAT-SPEC." :version "31.1" :type '(repeat string)) -- 2.39.5