Allow leading doc-strings when (re-)defining faces via :custom-face

README.md

@@ -499,6 +499,14 @@ The `:custom-face` keyword allows customization of package custom faces.
  (example-1-face ((t (:foreground "LightPink"))))
  (example-2-face ((t (:foreground "LightGreen"))) face-defspec-spec))
 
+(use-package org
+ :custom-face
+ (favorite-keywords-face
+ "Face for my favorite keywords \o/"
+ ((t (:background "LightBlue"))))
+ (org-special-keyword
+ ((t (:inherit favorite-keywords-face)))))
+
 (use-package zenburn-theme
  :preface
  (setq my/zenburn-colors-alist

use-package-core.el

@@ -1506,24 +1506,42 @@ no keyword implies `:all'."
 (defun use-package-normalize/:custom-face (name-symbol _keyword arg)
  "Normalize use-package custom-face keyword."
  (let ((error-msg
- (format "%s wants a (<symbol> <face-spec> [spec-type]) or list of these"
+ (format "%s wants a (<symbol> [<string>] <face-spec> [spec-type]) or list of these"
  name-symbol)))
  (unless (listp arg)
  (use-package-error error-msg))
- (cl-dolist (def arg arg)
- (unless (listp def)
- (use-package-error error-msg))
- (let ((face (nth 0 def))
- (spec (nth 1 def)))
- (when (or (not face)
- (not spec)
- (> (length def) 3))
- (use-package-error error-msg))))))
+ (cl-flet ((check-spec-type (spec-type)
+ (when (or (> (length spec-type) 1)
+ (and (car spec-type)
+ (not (symbolp (car spec-type)))))
+ (use-package-error error-msg))))
+ (cl-dolist (def arg arg)
+ (pcase def
+ ;; With doc-string
+ (`(,(and (pred symbolp) face)
+ ,(and (pred stringp) doc)
+ ,(and (pred (not null)) spec)
+ . ,spec-type)
+ (check-spec-type spec-type))
+ ;; Without doc-string
+ (`(,(and (pred symbolp) face)
+ ,(and (pred (not null)) spec)
+ . ,spec-type)
+ (check-spec-type spec-type))
+ (t (use-package-error error-msg)))))))
 
 (defun use-package-handler/:custom-face (name _keyword args rest state)
  "Generate use-package custom-face keyword code."
  (use-package-concat
- (mapcar #'(lambda (def) `(apply #'face-spec-set (backquote ,def))) args)
+ (mapcar #'(lambda (def)
+ (if (stringp (nth 1 def))
+ `(progn
+ (apply #'face-spec-set
+ (backquote ,(cons (car def) (cddr def))))
+ (set-face-doc-string (quote ,(car def))
+ ,(nth 1 def)))
+ `(apply #'face-spec-set (backquote ,def))))
+ args)
  (use-package-process-keywords name rest state)))
 
 ;;;; :init

use-package-tests.el

@@ -1176,6 +1176,24 @@
  (apply #'face-spec-set (backquote (foo ((t (:background "#e4edfc"))) face-defspec-spec)))
  (require 'foo nil nil))))
 
+(ert-deftest use-package-test/:custom-face-4 ()
+ (match-expansion
+ (use-package org
+ :custom-face
+ (favorite-keywords-face
+ "Face for my favorite keywords \o/"
+ ((t (:background "LightBlue"))))
+ (org-special-keyword
+ ((t (:inherit favorite-keywords-face)))))
+ `(progn
+ (progn
+ (apply #'face-spec-set
+ (backquote (favorite-keywords-face ((t (:background "LightBlue"))))))
+ (set-face-doc-string 'favorite-keywords-face "Face for my favorite keywords o/"))
+ (apply #'face-spec-set
+ (backquote (org-special-keyword ((t (:inherit favorite-keywords-face))))))
+ (require 'org nil nil))))
+
 (ert-deftest use-package-test/:init-1 ()
  (match-expansion
  (use-package foo :init (init))

use-package.texi

@@ -1236,6 +1236,14 @@ faces.
  (example-1-face ((t (:foreground "LightPink"))))
  (example-2-face ((t (:foreground "LightGreen"))) face-defspec-spec))
 
+(use-package org
+ :custom-face
+ (favorite-keywords-face
+ "Face for my favorite keywords \o/"
+ ((t (:background "LightBlue"))))
+ (org-special-keyword
+ ((t (:inherit favorite-keywords-face)))))
+
 (use-package zenburn-theme
  :preface
  (setq my/zenburn-colors-alist