0

Although I have the function mdoc to add to the documentation, I do not find it very convenient to add to the documentation after defining the function.

Rather, I would like to see how links in the documentation look like and how to make them. A specific type of link involves a making a clickable string which would direct one to additional text. Are there more ways to add more details to the documentation?

I am also interested in making links to the Emacs Manual and the Lisp Reference.

(defun mdoc (fname doc)
  "Appends a string to the documentation of a function.
 FNAME        Name of function
 DOC          Documentation"
  
  (put fname 'function-documentation
       (concat
         (documentation fname t) doc) ))
3
  • The question is unclear. No connection is made between "links" in the doc and the code you show, which, as you say, is only about adding text to the documentation. And no explanation of what you mean by "links" in this context.
    – Drew
    Jul 10, 2022 at 16:28
  • I think one can have a string in the function documentation that you can click on, which directs you to additional details.
    – Dilna
    Jul 10, 2022 at 16:31
  • 1
    See help-make-xrefs in help-mode.el. But those are specific kinds of links. You need to make your question more specific. Give an example of what you want to link to etc.
    – Drew
    Jul 10, 2022 at 16:35

1 Answer 1

1
  1. Copy the below snippet to a file ~/Downloads/usage.el.
(defgroup usage nil
  "Options for adding extra usage information to functions."
  :tag "Usage"
  :group 'help)

(require 'org)

(defcustom usage-alist
  '((cons .
          "
        (cons 1 '(2))
             ⇒ (1 2)

        (cons 1 '())
             ⇒ (1)

        (cons 1 2)
             ⇒ (1 . 2)
")
    (car .
         "
        (car '(a b c))
             ⇒ a

        (car '())
             ⇒ nil
")

    (cdr .
         "
        (cdr '(a b c))
             ⇒ (b c)

        (cdr '())
             ⇒ nil
"))
  "Alist of functions and extra documentation."
  :type `(repeat (cons
         (function :tag "Function symbol")
         (string :tag "Extra Documentation")
         ))
  :group 'usage)

(defface usage-face
  '((t (:background "yellow" :foreground "firebrick" :extend t)))
  "Face used for usage info."
  :group 'usage)

(add-hook 'help-fns-describe-function-functions
          #'help-fns--add-usage t)

(defun unindent-indent-and-propertize-string (s &optional n face)
  (setq n (or n 2))
  (setq face (or face 'usage-face))
  (propertize
   (with-temp-buffer
     (insert (org-remove-indentation s))
     (indent-rigidly (point-min) (point-max) n t)
     (buffer-string))
   'face face))

(defun help-fns--add-usage (function)
  (when-let ((usage (alist-get function usage-alist)))
    (with-current-buffer standard-output
      (insert "\n"
              (unindent-indent-and-propertize-string "Usage:" 2 'bold)
              "\n"
              (unindent-indent-and-propertize-string (concat usage "\n") 4)))))

(provide 'usage)

  1. Restart emacs with emacs -Q. (Note the -Q option)
  2. M-x load-file RET ~/Downloads/usage.el RET
  3. Do a C-h f cons. Do a M-x customize-group RET usage RET. You will see the following

Demo of above elisp snippet

FWIW, I have copied the usage information from

Building Cons Cells and Lists and Accessing Elements of Lists

which can be accessed within Emacs with

(info "(elisp) Building Lists")

and

(info "(elisp) List Elements")

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.