Function: shortdoc--keyword-plist-p

shortdoc--keyword-plist-p is a byte-compiled function defined in shortdoc.el.gz.

Signature

(shortdoc--keyword-plist-p OBJECT)

Documentation

Return non-nil if OBJECT is a plist with keywords as property names.

Source Code

;; Defined in /usr/src/emacs/lisp/emacs-lisp/shortdoc.el.gz
;; Almost all past Emacs versions (but see note on Emacs 30 below)
;; understand the following shortdoc group structure:
;;
;;  (SYMBOL                                 ;; shortdoc group name
;;   (:group [:KEYWORD VALUE ...])          ;; group properties
;;   STRING                                 ;; shortdoc section title
;;   (:section [:KEYWORD VALUE ...])        ;; section properties
;;
;;   (SYMBOL                                ;; shortdoc item
;;    [:KEYWORD VALUE ...])                 ;; item properties
;;   ([:item] FORM                          ;; generalized shortdoc item
;;    [:KEYWORD VALUE ...]))                ;; item properties
;;
;; Where:
;; - a group definition must contain at least one section title or item;
;; - group and section properties must occur at most once after the
;;   group name and a section title, respectively;
;; - the leading `:item' keyword of a generalized shortdoc item may be
;;   omitted if the shortdoc group is not intended to be used on Emacs
;;   versions older than Emacs 32;
;; - the group, secion, or item properties may be empty.
;;
;; That does not mean that any such shortdoc group is meaningful.  And
;; that does not mean that past Emacs version actually use all the bits
;; available in such a definition.  But they will not error out when
;; processing a definition with the format layed out above, they will
;; simply silently ignore those bits unknown to them (specifically
;; unknown keywords) and attempt to make the best out of the rest.
;;
;; Why is this important?  Because it gives package authors a guarantee
;; that they can use shortdoc features of newer Emacs versions without
;; older Emacs versions breaking on them.
;;
;; So Emacs developers, please
;;
;; - stick to above structure when extending shortdoc.el (so that past
;;   Emacs versions can grok your extensions without breaking); and
;;
;; - do not impose any additional restrictions on the format described
;;   above and on the allowed keywords (so that you do not limit the
;;   options of future Emacs versions).
;;
;; Emacs 30, for example, had introduced some restrictions on item
;; property keywords.  As a result, we need that hack mentioned in the
;; "boilerplate template for Emacs package authors" above.

(defun shortdoc--keyword-plist-p (object)
  "Return non-nil if OBJECT is a plist with keywords as property names."
  (let ((ok (proper-list-p object)))
    (while (and ok object)
      (setq ok (and (keywordp (car object)) (cdr object))
            object (cddr object)))
    ok))