Function: define-short-documentation-group

define-short-documentation-group is a macro defined in shortdoc.el.gz.

Signature

(define-short-documentation-group GROUP &rest FUNCTIONS)

Documentation

Add GROUP to the list of defined documentation groups.

FUNCTIONS is a list of elements on the form:

  (FUNC
   :no-manual BOOL
   :args ARGS
   :eval EVAL
   :no-eval EXAMPLE-FORM
   :no-value EXAMPLE-FORM
   :no-eval* EXAMPLE-FORM
   :result RESULT-FORM
   :result-string RESULT-STRING
   :eg-result RESULT-FORM
   :eg-result-string RESULT-STRING)

FUNC is the function being documented.

NO-MANUAL should be non-nil if FUNC isn't documented in the manual.

ARGS is optional list of function FUNC's arguments. FUNC's signature is displayed automatically if ARGS is not present. Specifying ARGS might be useful where you don't want to document some of the uncommon arguments a function might have.

While the :no-manual and :args property can be used for any (FUNC ..) form, all of the other properties shown above cannot be used simultaneously in such a form.

Here are some common forms with examples of properties that go together:

1. Document a form or string, and its evaluated return value.
   (FUNC
    :eval EVAL)

If EVAL is a string, it will be inserted as is, and then that string will be read and evaluated.

2. Document a form or string, but manually document its evaluation
   result. The provided form will not be evaluated.

  (FUNC
   :no-eval EXAMPLE-FORM
   :result RESULT-FORM) ;Use :result-string if value is in string form

Using :no-value is the same as using :no-eval.

Use :no-eval* instead of :no-eval where the successful execution of the documented form depends on some conditions.

3. Document a form or string EXAMPLE-FORM. Also manually
   document an example result. This result could be unrelated to
   the documented form.

  (FUNC
   :no-eval EXAMPLE-FORM
   :eg-result RESULT-FORM) ;Use :eg-result-string if value is in string form

A FUNC form can have any number of :no-eval (or :no-value),
:no-eval*, :result, :result-string, :eg-result and
:eg-result-string properties.

View in manual

Source Code

;; Defined in /usr/src/emacs/lisp/emacs-lisp/shortdoc.el.gz
;;;###autoload
(progn
  (defvar shortdoc--groups nil)

  (defmacro define-short-documentation-group (group &rest functions)
    "Add GROUP to the list of defined documentation groups.
FUNCTIONS is a list of elements on the form:

  (FUNC
   :no-manual BOOL
   :args ARGS
   :eval EVAL
   :no-eval EXAMPLE-FORM
   :no-value EXAMPLE-FORM
   :no-eval* EXAMPLE-FORM
   :result RESULT-FORM
   :result-string RESULT-STRING
   :eg-result RESULT-FORM
   :eg-result-string RESULT-STRING)

FUNC is the function being documented.

NO-MANUAL should be non-nil if FUNC isn't documented in the
manual.

ARGS is optional list of function FUNC's arguments.  FUNC's
signature is displayed automatically if ARGS is not present.
Specifying ARGS might be useful where you don't want to document
some of the uncommon arguments a function might have.

While the `:no-manual' and `:args' property can be used for
any (FUNC ..) form, all of the other properties shown above
cannot be used simultaneously in such a form.

Here are some common forms with examples of properties that go
together:

1. Document a form or string, and its evaluated return value.
   (FUNC
    :eval EVAL)

If EVAL is a string, it will be inserted as is, and then that
string will be `read' and evaluated.

2. Document a form or string, but manually document its evaluation
   result.  The provided form will not be evaluated.

  (FUNC
   :no-eval EXAMPLE-FORM
   :result RESULT-FORM)   ;Use `:result-string' if value is in string form

Using `:no-value' is the same as using `:no-eval'.

Use `:no-eval*' instead of `:no-eval' where the successful
execution of the documented form depends on some conditions.

3. Document a form or string EXAMPLE-FORM.  Also manually
   document an example result.  This result could be unrelated to
   the documented form.

  (FUNC
   :no-eval EXAMPLE-FORM
   :eg-result RESULT-FORM) ;Use `:eg-result-string' if value is in string form

A FUNC form can have any number of `:no-eval' (or `:no-value'),
`:no-eval*', `:result', `:result-string', `:eg-result' and
`:eg-result-string' properties."
    (declare (indent defun))
    `(progn
       (setq shortdoc--groups (delq (assq ',group shortdoc--groups)
                                    shortdoc--groups))
       (push (cons ',group ',functions) shortdoc--groups))))