by using the @kbd{M-x shortdoc} command. This will prompt you for an
area of interest, e.g., @code{string}, and pop you to a buffer where
many of the functions relevant for handling strings are listed.
-Here's an example you can include in your initialization file
-(@pxref{Init File}) that uses @code{shortdoc} to insert Emacs Lisp
-function examples into regular @file{*Help*} buffers when you use
-@kbd{C-h f}:
+
+You can also request that documentation of functions and commands
+shown in @file{*Help*} buffers popped by @kbd{C-h f} includes examples
+of their use. To that end, add the following to your initialization
+file (@pxref{Init File}):
@example
(add-hook 'help-fns-describe-function-functions
@defun shortdoc-function-examples function
This function returns all shortdoc examples for @var{function}. The
-result is an alist with items of the form
-
-@example
-(@var{group} . @var{examples})
-@end example
-
-@noindent
-where @var{group} is a documentation group where @var{function}
-appears in and @var{examples} is a string with the examples of use of
-@var{function} defined in @var{group}.
+return value is an alist with items of the form
+@w{@code{(@var{group} . @var{examples})}}, where @var{group} is a
+documentation group where @var{function} appears, and @var{examples}
+is a string with the examples of @var{function}s use as defined in
+@var{group}.
@code{shortdoc-function-examples} returns @code{nil} if @var{function}
-is not a function or if it doesn’t contain shortdoc information.
+is not a function or if it doesn't have any shortdoc examples.
@end defun
+@vindex help-fns-describe-function-functions
@defun shortdoc-help-fns-examples-function function
-This function queries the registered documentation groups and inserts
-examples of use of a given Emacs Lisp function into the current
-buffer.
+This function queries the registered shortdoc groups and inserts
+examples of use of a given Emacs Lisp @var{function} into the current
+buffer. It is suitable for addition to the
+@code{help-fns-describe-function-functions} hook, in which case
+examples from shortdoc of using a function will be displayed in the
+@file{*Help*} buffer when the documentation of the function is
+requested.
@end defun
+++
*** New function 'shortdoc-function-examples'.
-This function queries the registered documentation groups and returns
-examples of use of a given Emacs Lisp function.
+This function returns examples of use of a given Emacs Lisp function
+from the available shortdoc information.
+++
*** New function 'shortdoc-help-fns-examples-function'.
-This function queries the registered documentation groups and inserts
-examples of use of a given Emacs Lisp function into the current
-buffer. If you want to insert Emacs Lisp function examples into
-regular *Help* buffers when you use 'describe-function', add the
+This function inserts into the current buffer examples of use of a
+given Emacs Lisp function, which it gleans from the shortdoc
+information. If you want 'describe-function' ('C-h f') to insert
+examples of using the function into regular *Help* buffers, add the
following to you init file:
(add-hook 'help-fns-describe-function-functions
(beginning-of-line)))
(defun shortdoc--insert-group-in-buffer (group &optional buf)
- "Insert a short documentation summary for functions in GROUP in buffer BUF."
+ "Insert a short documentation summary for functions in GROUP in buffer BUF.
+BUF defaults to the current buffer if nil or omitted."
(with-current-buffer (or buf (current-buffer))
(let ((inhibit-read-only t)
(prev nil))
(defun shortdoc-function-examples (function)
"Return all shortdoc examples for FUNCTION.
The result is an alist with items of the form (GROUP . EXAMPLES),
-where GROUP is a shortdoc group where FUNCTION appears in and
+where GROUP is a shortdoc group where FUNCTION appears, and
EXAMPLES is a string with the usage examples of FUNCTION defined
in GROUP. Return nil if FUNCTION is not a function or if it
-doesn't contain shortdoc information."
+doesn't has any shortdoc information."
(let ((groups (and (symbolp function)
(shortdoc-function-groups function)))
(examples nil))
(with-temp-buffer
(shortdoc--insert-group-in-buffer group)
(goto-char (point-min))
- (setq match (text-property-search-forward
- 'shortdoc-example function t))
- (push `(,group . ,(string-trim
- (buffer-substring-no-properties
- (prop-match-beginning match)
- (prop-match-end match))))
- examples)))
+ (let ((match (text-property-search-forward
+ 'shortdoc-example function t)))
+ (push `(,group . ,(string-trim
+ (buffer-substring-no-properties
+ (prop-match-beginning match)
+ (prop-match-end match))))
+ examples))))
groups)
examples))
(defun shortdoc-help-fns-examples-function (function)
"Insert Emacs Lisp examples for FUNCTION into the current buffer.
-You can add this function to the
-`help-fns-describe-function-functions' list to show function
-example documentation in *Help* buffers."
+You can add this function to the `help-fns-describe-function-functions'
+hook to show examples of using FUNCTION in *Help* buffers produced
+by \\[describe-function]."
(let ((examples (shortdoc-function-examples function))
(times 0))
(dolist (example examples)
(when (zerop times)
(if (eq (length examples) 1)
- (insert " Example:\n\n")
- (insert " Examples:\n\n")))
+ (insert "\n Example:\n\n")
+ (insert "\n Examples:\n\n")))
(setq times (1+ times))
(insert " ")
(insert (cdr example))
projects / emacs.git / commitdiff