[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
master 4b84095: Improve documentation of shortdoc features
From: |
Eli Zaretskii |
Subject: |
master 4b84095: Improve documentation of shortdoc features |
Date: |
Sun, 11 Oct 2020 10:30:12 -0400 (EDT) |
branch: master
commit 4b84095d2373eb0b26308d6c622ce9ab89a0efa5
Author: Eli Zaretskii <eliz@gnu.org>
Commit: Eli Zaretskii <eliz@gnu.org>
Improve documentation of shortdoc features
* lisp/help-fns.el (help-fns-describe-function-functions): Doc
fix.
* lisp/emacs-lisp/shortdoc.el (define-short-documentation-group)
(shortdoc-display-group, shortdoc-add-function): Doc fixes.
* doc/lispref/help.texi (Documentation Groups): Improve the
recently-added documentation and the indexing.
---
doc/lispref/help.texi | 105 ++++++++++++++++++++++++--------------------
lisp/emacs-lisp/shortdoc.el | 13 +++---
lisp/help-fns.el | 4 +-
3 files changed, 67 insertions(+), 55 deletions(-)
diff --git a/doc/lispref/help.texi b/doc/lispref/help.texi
index f513a70..2fa54e3 100644
--- a/doc/lispref/help.texi
+++ b/doc/lispref/help.texi
@@ -800,76 +800,64 @@ if the user types the help character again.
@node Documentation Groups
@section Documentation Groups
@cindex documentation groups
+@cindex groups of functions
+@cindex function 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.
+of functions that operate on strings.
The documentation groups are created with the
-@code{define-short-documentation-group} macro. Here's a very short
-example:
+@code{define-short-documentation-group} macro.
+
+@defmac define-short-documentation-group group &rest functions
+Define @var{group} as a group of functions, and provide short
+summaries of using those functions. The optional argument
+@var{functions} is a list whose elements are of the form:
@lisp
-(define-short-documentation-group string
- "Creating Strings"
- (substring
- :eval (substring "foobar" 0 3)
- :eval (substring "foobar" 3))
- (concat
- :eval (concat "foo" "bar" "zot")))
+(@var{func} @var{keyword} @var{val} @dots{})
@end lisp
-The first argument is the name of the group to be defined, and then
-follows any number of function descriptions.
-
-A function can belong to any number of documentation groups.
-
-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:
+The following keywords are recognized:
@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:
+The value should be a form that has no side effect when evaluated.
+The form will be used in the documentation by printing it with
+@code{prin1} (@pxref{Output Functions}). However, if the form is a
+string, it will be inserted as-is, and the string will then be
+@code{read} to yield 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
+@noindent
will be printed as
@example
(concat "foo" "bar" "zot")
-=> "foobarzot"
+@result{} "foobarzot"
(make-string 5 ?x)
-=> "xxxxx"
+@result{} "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
+(The reason for allowing both Lisp forms and strings here is so that
+printing could 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.
+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.
+This is like @code{:eval}, except that the form will not be evaluated.
+In these cases, a @code{:result} element of some kind (see below)
+should be included.
@example
:no-eval (file-symlink-p "/tmp/foo")
@@ -877,8 +865,8 @@ included.
@end example
@item :no-eval*
-Like @code{:no-eval}, but a result of @samp{[it depends]} will always
-be inserted.
+Like @code{:no-eval}, but alaways inserts @samp{[it depends]} as the
+result.
@example
:no-eval* (buffer-string)
@@ -888,12 +876,12 @@ will result in:
@example
(buffer-string)
--> [it depends]
+@click{} [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.
+well-defined return value, and is used for side effect only.
@item :result
Used to output the result from non-evaluating example forms.
@@ -925,11 +913,11 @@ is unreadable or should be on a particular form:
@end example
@item :no-manual
-This function is not documented in the manual.
+Indicates that this function is not documented in the manual.
@item :args
By default, the function's actual argument list is shown. If
-@code{:args} is present, use that instead.
+@code{:args} is present, they are used instead.
@example
:args (regexp string)
@@ -937,9 +925,32 @@ By default, the function's actual argument list is shown.
If
@end table
+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.
+
+@end defmac
+
+A function can belong to any number of documentation groups.
+
+In addition to function descriptions, the list can also have string
+elements, which are used to divide a documentation group into
+sections.
+
@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.
+Lisp packages can add functions to groups with this command. Each
+@var{elem} should be a function descriptions, as described above.
@var{group} is the function group, and @var{section} is what section
in the function group to insert the function into.
diff --git a/lisp/emacs-lisp/shortdoc.el b/lisp/emacs-lisp/shortdoc.el
index 1843db8..eaa4ece 100644
--- a/lisp/emacs-lisp/shortdoc.el
+++ b/lisp/emacs-lisp/shortdoc.el
@@ -67,13 +67,13 @@ FUNCTIONS is a list of elements on the form:
BOOL should be non-nil if the function isn't documented in the
manual.
-ARGS is optional, and the functions definition is displayed
-instead in not present.
+ARGS is optional; the function's signature is displayed if ARGS
+is not present.
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
+evaluated 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.
+and then evaluated.
There can be any number of :example/:result elements."
`(progn
@@ -957,8 +957,8 @@ There can be any number of :example/:result elements."
;;;###autoload
(defun shortdoc-display-group (group)
- "Pop to a buffer and display short documentation for functions in GROUP."
- (interactive (list (completing-read "Show functions in: "
+ "Pop to a buffer with short documentation summary for functions in GROUP."
+ (interactive (list (completing-read "Show summary for functions in: "
(mapcar #'car shortdoc--groups))))
(when (stringp group)
(setq group (intern group)))
@@ -1079,6 +1079,7 @@ There can be any number of :example/:result elements."
(defun shortdoc-add-function (group section elem)
"Add ELEM to shortdoc GROUP in SECTION.
+If GROUP doesn't exist, it will be created.
If SECTION doesn't exist, it will be added.
Example:
diff --git a/lisp/help-fns.el b/lisp/help-fns.el
index ee626eb..07b4c40 100644
--- a/lisp/help-fns.el
+++ b/lisp/help-fns.el
@@ -40,8 +40,8 @@
(defvar help-fns-describe-function-functions nil
"List of functions to run in help buffer in `describe-function'.
Those functions will be run after the header line and argument
-list was inserted, and before the documentation will be inserted.
-The functions will receive the function name as argument.
+list was inserted, and before the documentation is be inserted.
+The functions will be called with one argument: the function's symbol.
They can assume that a newline was output just before they were called,
and they should terminate any of their own output with a newline.
By convention they should indent their output by 2 spaces.")
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- master 4b84095: Improve documentation of shortdoc features,
Eli Zaretskii <=