scratch/shortdoc d1ff4cc: Allow headings and rearrange the strings

[Lars Ingebrigtsen]

branch: scratch/shortdoc
commit d1ff4cc9cf0a69eb96fc6098336b6b71526c963b
Author: Lars Ingebrigtsen <larsi@gnus.org>
Commit: Lars Ingebrigtsen <larsi@gnus.org>

    Allow headings and rearrange the strings
---
 lisp/emacs-lisp/shortdoc.el | 178 +++++++++++++++++++++++++-------------------
 1 file changed, 101 insertions(+), 77 deletions(-)

diff --git a/lisp/emacs-lisp/shortdoc.el b/lisp/emacs-lisp/shortdoc.el
index 071002b..b9d0cf2 100644
--- a/lisp/emacs-lisp/shortdoc.el
+++ b/lisp/emacs-lisp/shortdoc.el
@@ -52,7 +52,8 @@ FUNCTIONS is a list of elements on the form:
   (fun
    :no-manual BOOL
    :args ARGS
-   :example FORM)
+   :example EXAMPLE-FORM
+   :result RESULT-FORM)
 
 BOOL should be non-nil if the function isn't documented in the
 manual.
@@ -60,13 +61,42 @@ manual.
 ARGS is optional, and the functions definition is displayed
 instead in not present.
 
-There can be any number of :example/:result pairs."
-  `(progn
+If EXAMPLE-FORM isn't a string, it will be printed with `prin1',
+and then evaled to give a result, which is also printed.  If it's
+a string, it'll be inserted as is.  In that case, there should be
+a form that says what the result should be.
+
+There can be any number of :example/:result elements."
+  `(eval-and-compile
      (setq shortdoc--groups (delq (assq ',group shortdoc--groups)
                                   shortdoc--groups))
      (push (cons ',group ',functions) shortdoc--groups)))
 
 (define-short-documentation-group string
+  "Making Strings"
+  (make-string
+   :example "(make-string 5 ?x)"
+   :result "xxxxx")
+  (string
+   :example "(string ?a ?b ?c)"
+   :result "abc")
+  (concat
+   :example (concat "foo" "bar" "zot"))
+  (string-join
+   :example (string-join '("foo" "bar" "zot") " "))
+  (mapconcat
+   :example (mapconcat (lambda (a) (concat "[" a "]"))
+                       '("foo" "bar" "zot") " "))
+  (format
+   :example (format "This number is %d" 4))
+  "Manipulating Strings"
+  (substring
+   :example (substring "foobar" 0 3)
+   :example (substring "foobar" 3))
+  (split-string
+   :example (split-string "foo bar")
+   :example (split-string "|foo|bar|" "|")
+   :example (split-string "|foo|bar|" "|" t))
   (string-trim
    :no-manual t
    :args (string)
@@ -78,24 +108,26 @@ There can be any number of :example/:result pairs."
   (string-trim-right
    :no-manual t
    :example (string-trim-right "barkss" "s+"))
-  (concat
-   :example (concat "foo" "bar" "zot"))
-  (string-join
-   :example (string-join '("foo" "bar" "zot") " "))
-  (mapconcat
-   :example (mapconcat (lambda (a) (concat "[" a "]"))
-                       '("foo" "bar" "zot") " "))
-  (make-string
-   :example (make-string 5 ?x))
-  (string
-   :example (string ?a ?b ?c))
-  (substring
-   :example (substring "foobar" 0 3)
-   :example (substring "foobar" 3))
+  (string-truncate-left
+   :example (string-truncate-left "longstring" 8))
+  (string-remove-suffix
+   :example (string-remove-suffix "bar" "foobar"))
+  (string-remove-prefix
+   :example (string-remove-prefix "foo" "foobar"))
+  (reverse
+   :example (reverse "foo"))
   (substring-no-properties
    :example (substring (propertize "foobar" 'face 'bold) 0 3))
+  "Predicates for String"
   (string-equal
    :example (string-equal "foo" "foo"))
+  (stringp
+   :example "(stringp ?a)"
+   :result t)
+  (string-empty-p
+   :example (string-empty-p ""))
+  (string-blank-p
+   :example (string-blank-p " \n"))
   (string-lessp
    :example (string-lessp "foo" "bar"))
   (string-greaterp
@@ -106,6 +138,7 @@ There can be any number of :example/:result pairs."
    :example (string-prefix-p "foo" "foobar"))
   (string-suffix-p
    :example (string-suffix-p "bar" "foobar"))
+  "Case Manipulation"
   (upcase
    :example (upcase "foo"))
   (downcase
@@ -114,35 +147,18 @@ There can be any number of :example/:result pairs."
    :example (capitalize "foo bar zot"))
   (upcase-initials
    :example (upcase-initials "The CAT in the hAt"))
+  "Converting Strings"
   (string-to-number
    :example (string-to-number "42")
    :example (string-to-number "deadbeef" 16))
   (number-to-string
    :example (number-to-string 42))
+  "Data About Strings"
   (length
    :example (length "foo"))
-  (reverse
-   :example (reverse "foo"))
   (seq-position
-   :example (seq-position "foobarzot" ?z))
-  (format
-   :example (format "This number is %d" 4))
-  (stringp
-   :example (stringp ?a))
-  (string-empty-p
-   :example (string-empty-p ""))
-  (string-blank-p
-   :example (string-blank-p " \n"))
-  (string-truncate-left
-   :example (string-truncate-left "longstring" 8))
-  (string-remove-suffix
-   :example (string-remove-suffix "bar" "foobar"))
-  (string-remove-prefix
-   :example (string-remove-prefix "foo" "foobar"))
-  (split-string
-   :example (split-string "foo bar")
-   :example (split-string "|foo|bar|" "|")
-   :example (split-string "|foo|bar|" "|" t)))
+   :example "(seq-position \"foobarzot\" ?z)"
+   :result 6))
 
 (defun shortdoc-display-group (group)
   "Pop to a buffer and display short documentation for functions in GROUP."
@@ -155,48 +171,56 @@ There can be any number of :example/:result pairs."
     (button-mode)
     (mapc
      (lambda (data)
-       (let ((function (pop data))
-             (start-section (point)))
-         ;; Function calling convention.
-         (insert "(")
-         (if (getf data :no-manual)
-             (insert (symbol-name function))
-           (insert-text-button
-            (symbol-name function)
-            'face 'button
-            'action (lambda (_)
-                      (info-lookup-symbol function 'emacs-lisp-mode))))
-         (dolist (param (or (plist-get data :args)
-                            (help-function-arglist function t)))
-           (insert " " (symbol-name param)))
-         (insert ")\n")
-         ;; Doc string.
-         (insert "  "
-                 (or (plist-get data :doc)
-                     (car (split-string (documentation function) "\n"))))
-         (insert "\n\n")
-         (add-face-text-property start-section (point) 'shortdoc-section t)
-         (let ((start (point))
-               (print-escape-newlines t))
-           (cl-loop for (type value) on data by #'cddr
-                    when (eq type :example)
-                    do (progn
-                         (insert "  ")
-                         (prin1 value (current-buffer))
-                         (insert "\n")
-                         (insert "    => ")
-                         (prin1 (eval value) (current-buffer))
-                         (insert "\n"))
-                    when (eq type :result)
-                    do (progn
-                         (insert "    => ")
-                         (prin1 value (current-buffer))
-                         (insert "\n")))
-           (put-text-property start (point) 'face 'shortdoc-example))
-         (insert "\n")))
+       (if (stringp data)
+           (insert (propertize
+                    (concat data "\n\n")
+                    'face '(variable-pitch (:height 1.3 :weight bold))))
+         (shortdoc--display-function data)))
      (cdr (assq group shortdoc--groups))))
   (goto-char (point-min)))
 
+(defun shortdoc--display-function (data)
+  (let ((function (pop data))
+        (start-section (point)))
+    ;; Function calling convention.
+    (insert "(")
+    (if (getf data :no-manual)
+        (insert (symbol-name function))
+      (insert-text-button
+       (symbol-name function)
+       'face 'button
+       'action (lambda (_)
+                 (info-lookup-symbol function 'emacs-lisp-mode))))
+    (dolist (param (or (plist-get data :args)
+                       (help-function-arglist function t)))
+      (insert " " (symbol-name param)))
+    (insert ")\n")
+    ;; Doc string.
+    (insert "  "
+            (or (plist-get data :doc)
+                (car (split-string (documentation function) "\n"))))
+    (insert "\n\n")
+    (add-face-text-property start-section (point) 'shortdoc-section t)
+    (let ((start (point))
+          (print-escape-newlines t))
+      (cl-loop for (type value) on data by #'cddr
+               when (eq type :example)
+               do (if (stringp value)
+                      (insert "  " value "\n")
+                    (insert "  ")
+                    (prin1 value (current-buffer))
+                    (insert "\n")
+                    (insert "    => ")
+                    (prin1 (eval value) (current-buffer))
+                    (insert "\n"))
+               when (eq type :result)
+               do (progn
+                    (insert "    => ")
+                    (prin1 value (current-buffer))
+                    (insert "\n")))
+      (put-text-property start (point) 'face 'shortdoc-example))
+    (insert "\n")))
+
 (defun shortdoc-function-groups (function)
   "Return all shortdoc groups FUNCTION appears in."
   (cl-loop for group in shortdoc--groups