scratch/shortdoc 54bfea8: Start adding documentation of the shortdoc stuff

[Lars Ingebrigtsen]

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

    Start adding documentation of the shortdoc stuff
---
 doc/lispref/help.texi       | 139 ++++++++++++++++++++++++++++++++++++++++++++
 lisp/emacs-lisp/shortdoc.el |  43 ++++++++------
 2 files changed, 164 insertions(+), 18 deletions(-)

diff --git a/doc/lispref/help.texi b/doc/lispref/help.texi
index d4505d5..f6e1b16 100644
--- a/doc/lispref/help.texi
+++ b/doc/lispref/help.texi
@@ -37,6 +37,7 @@ Help, emacs, The GNU Emacs Manual}.
 * Describing Characters::     Making printable descriptions of
                                 non-printing characters and key sequences.
 * Help Functions::            Subroutines used by Emacs help facilities.
+* Documentation Groups::      Listing functions by groups.
 @end menu
 
 @node Documentation Basics
@@ -794,3 +795,141 @@ If this variable is non-@code{nil}, commands defined with
 echo area at first, and display the longer @var{help-text} strings only
 if the user types the help character again.
 @end defopt
+
+
+@node Documentation Groups
+@section Documentation Groups
+@cindex documentation groups
+
+Emacs can list functions based on various groupings.  For instance,
+@code{string-trim} and @code{mapconcat} are ``string'' functions, so
+@kbd{M-x shortdoc-display-group RET string RET} will give an overview
+of functions that do things with strings.
+
+The documentation groups are created with the
+@code{define-short-documentation-group} macro.  Here's a very short
+example:
+
+@lisp
+(define-short-documentation-group string
+  "Creating Strings"
+  (substring
+   :eval (substring "foobar" 0 3)
+   :eval (substring "foobar" 3))
+  (concat
+   :eval (concat "foo" "bar" "zot")))
+@end lisp
+
+The first argument is the name of the group to be defined, and then
+follows any number of function descriptions.
+
+In addition to function descriptions, the list can also have string
+elements, which are used to divide a documentation group into
+sections.
+
+In each function description, the first element is the name of the
+function, and then the rest of the description is a plist, where the
+first element in each pair is a type, and the second element is a
+value.
+
+The following types are allowed:
+
+@table @code
+@item :eval
+The value should be a form that can be evaluated with no side
+effects.  The form will be used in the documentation as printed with
+@code{prin1}, except if it's a string: Then it will be inserted as is,
+and the string with then be @code{read} to return the form.  In any
+case, the form will then be evaluated, and the result used.  For
+instance:
+
+@example
+:eval (concat "foo" "bar" "zot")
+:eval "(make-string 5 ?x)"
+@end example
+
+will be printed as
+
+@example
+(concat "foo" "bar" "zot")
+=> "foobarzot"
+(make-string 5 ?x)
+=> "xxxxx"
+@end example
+
+The reason for allowing both Lisp forms and strings here is so that
+printing can be controlled in the few cases where a certain
+presentation of the form is wished for.  In the example, @samp{?x}
+would otherwise have been printed as @samp{120} if it hadn't been
+included in a string.
+
+@item :no-eval
+
+This is like @code{eval}, except that the form will not be evaluated.
+In these cases, a @code{:result} element of some kind should be
+included.
+
+@example
+:no-eval (file-symlink-p "/tmp/foo")
+:eg-result t
+@end example
+
+@item :no-eval*
+Like @code{:no-eval}, but a result of @samp{[it depends]} will always
+be inserted.
+
+@example
+:no-eval* (buffer-string)
+@end example
+
+will result in:
+
+@example
+(buffer-string)
+-> [it depends]
+@end example
+
+@item :no-value
+Like @code{:no-eval}, but is used when the function in question has no
+well-defined return value, but is used for side effect only.
+
+@item :result
+Used to output the result from non-evaluating example forms.
+
+@example
+:no-eval (setcar list 'c)
+:result c
+@end example
+
+@item :eg-result
+Used to output an example result from non-evaluating example forms.
+
+@example
+:no-eval (looking-at "f[0-9]")
+:eg-result t
+@end example
+
+@item :result-string
+@itemx :eg-result-string
+These two are the same as @code{:result} and @code{:eg-result},
+respectively, but are inserted as is.  This is useful when the result
+is unreadable or should be on a particular form:
+
+@example
+:no-eval (find-file "/tmp/foo")
+:eg-result-string "#<buffer foo>"
+:no-eval (default-file-modes)
+:eg-result-string "#o755"
+@end example
+
+@end table
+
+@defun shortdoc-add-function shortdoc-add-function group section elem
+External packages can add functions to groups with this command.  Each
+@var{elem} should be a function descriptions, as seen above.
+@var{group} is the function group, and @var{section} is what section
+in the function group to insert the function into.
+
+If @var{group} doesn't exist, it will be created.  If @var{section}
+doesn't exist, it will be added to the end of the function group.
+@end defun
diff --git a/lisp/emacs-lisp/shortdoc.el b/lisp/emacs-lisp/shortdoc.el
index 65aa8b5..293cd9e 100644
--- a/lisp/emacs-lisp/shortdoc.el
+++ b/lisp/emacs-lisp/shortdoc.el
@@ -57,8 +57,12 @@ FUNCTIONS is a list of elements on the form:
   (fun
    :no-manual BOOL
    :args ARGS
-   :example EXAMPLE-FORM
-   :result RESULT-FORM)
+   :eval EXAMPLE-FORM
+   :no-eval EXAMPLE-FORM
+   :no-value EXAMPLE-FORM
+   :result RESULT-FORM
+   :eg-result RESULT-FORM
+   :eg-result-string RESULT-FORM)
 
 BOOL should be non-nil if the function isn't documented in the
 manual.
@@ -66,10 +70,10 @@ manual.
 ARGS is optional, and the functions definition is displayed
 instead in not present.
 
-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.
+If EVAL 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, then the string will be `read',
+and then evaled.
 
 There can be any number of :example/:result elements."
   `(progn
@@ -81,11 +85,9 @@ There can be any number of :example/:result elements."
   "Making Strings"
   (make-string
    :args (length init)
-   :eval "(make-string 5 ?x)"
-   :result "xxxxx")
+   :eval "(make-string 5 ?x)")
   (string
-   :eval "(string ?a ?b ?c)"
-   :result "abc")
+   :eval "(string ?a ?b ?c)")
   (concat
    :eval (concat "foo" "bar" "zot"))
   (string-join
@@ -138,8 +140,7 @@ There can be any number of :example/:result elements."
   (string-equal
    :eval (string-equal "foo" "foo"))
   (stringp
-   :eval "(stringp ?a)"
-   :result t)
+   :eval "(stringp ?a)")
   (string-empty-p
    :no-manual t
    :eval (string-empty-p ""))
@@ -179,8 +180,7 @@ There can be any number of :example/:result elements."
   (assoc-string
    :eval (assoc-string "foo" '(("a" 1) (foo 2))))
   (seq-position
-   :eval "(seq-position \"foobarzot\" ?z)"
-   :result 6))
+   :eval "(seq-position \"foobarzot\" ?z)"))
 
 (define-short-documentation-group file-name
   "File Name Manipulation"
@@ -361,8 +361,7 @@ There can be any number of :example/:result elements."
    :no-eval (file-modes-symbolic-to-number "a+r")
    :eg-result-string "#o444")
   (file-modes-number-to-symbolic
-   :eval "(file-modes-number-to-symbolic #o444)"
-   :result "-r--r--r--")
+   :eval "(file-modes-number-to-symbolic #o444)")
   (set-file-extended-attributes
    :no-eval (set-file-extended-attributes
              "/tmp/foo" '((acl . "group::rxx")))
@@ -559,7 +558,7 @@ There can be any number of :example/:result elements."
    :no-eval (re-search-backward "^foo$" nil t)
    :eg-result 43)
   (looking-at-p
-   :no-eval (looking-at "f[0-9")
+   :no-eval (looking-at "f[0-9]")
    :eg-result t)
   "Utilities"
   (regexp-quote
@@ -760,6 +759,10 @@ There can be any number of :example/:result elements."
 
 (defun shortdoc-display-group (group)
   "Pop to a buffer and display short documentation for functions in GROUP."
+  (interactive (list (completing-read "Show functions in: "
+                                      (mapcar #'car shortdoc--groups))))
+  (when (stringp group)
+    (setq group (intern group)))
   (unless (assq group shortdoc--groups)
     (error "No such documentation group %s" group))
   (pop-to-buffer (format "*Shortdoc %s*" group))
@@ -841,6 +844,10 @@ There can be any number of :example/:result elements."
                  (insert "    => ")
                  (prin1 value (current-buffer))
                  (insert "\n"))
+                (:result-string
+                 (insert "    => ")
+                 (princ value (current-buffer))
+                 (insert "\n"))
                 (:eg-result
                  (insert "    eg. => ")
                  (prin1 value (current-buffer))
@@ -874,7 +881,7 @@ Example:
     (let ((slist (member section glist)))
       (unless slist
         (setq slist (list section))
-        (append glist slist))
+        (setq slist (append glist slist)))
       (while (and (cdr slist)
                   (not (stringp (cadr slist))))
         (setq slist (cdr slist)))