Skip to content

Commit

Permalink
Add buttons for shortdoc groups when shortdoc.el is available
Browse files Browse the repository at this point in the history
Emacs 28 added shortdoc.el and added many builtin functions into
shortdoc groups accessed through the help buffer. For example, this is
the help buffer for `mapcar`:

    Apply FUNCTION to each element of SEQUENCE, and make a list of the results.
    The result is a list just as long as SEQUENCE.
    SEQUENCE may be a list, a vector, a bool-vector, or a string.

      Other relevant functions are documented in the vector, list and
      string groups.
      Probably introduced at or before Emacs version 1.4.

This commit adds the same line into Helpful so it looks like this:

    Signature
    (mapcar FUNCTION SEQUENCE)

    Documentation
    Apply FUNCTION to each element of SEQUENCE, and make a list of the results.

    The result is a list just as long as SEQUENCE.
    SEQUENCE may be a list, a vector, a bool-vector, or a string.

    Other relevant functions are documented in the vector, list and string groups.

    View in manual
  • Loading branch information
kisaragi-hiu authored and Wilfred committed Apr 12, 2022
1 parent 67cdd10 commit c2729a2
Showing 1 changed file with 36 additions and 0 deletions.
36 changes: 36 additions & 0 deletions helpful.el
Original file line number Diff line number Diff line change
Expand Up @@ -748,6 +748,17 @@ whether the symbol represents a variable or a callable."
"Describe the symbol that this BUTTON represents."
(info (button-get button 'info-node)))

(define-button-type 'helpful-shortdoc-button
'action #'helpful--shortdoc
'info-node nil
'follow-link t
'help-echo "View this Shortdoc group")

(defun helpful--shortdoc (button)
"Describe the symbol that this BUTTON represents."
(shortdoc-display-group (button-get button 'shortdoc-group)
(button-get button 'symbol)))

(defun helpful--split-first-line (docstring)
"If the first line is a standalone sentence, ensure we have a
blank line afterwards."
Expand Down Expand Up @@ -1256,6 +1267,11 @@ If the source code cannot be found, return the sexp used."
;; TODO: offer to download C sources for current version.
(throw 'source (indirect-function sym)))))

(defun helpful--has-shortdoc-p (sym)
"Return non-nil if shortdoc.el is available and SYM is in a shortdoc group."
(and (featurep 'shortdoc)
(shortdoc-function-groups sym)))

(defun helpful--in-manual-p (sym)
"Return non-nil if SYM is in an Info manual."
(let ((completions
Expand Down Expand Up @@ -1732,6 +1748,21 @@ POSITION-HEADS takes the form ((123 (defun foo)) (456 (defun bar)))."
(kill-buffer buf)
return-value)))

(defun helpful--make-shortdoc-sentence (sym)
"Make a line for shortdoc groups of SYM."
(when (featurep 'shortdoc)
(-when-let (groups (--map (helpful--button
(symbol-name it)
'helpful-shortdoc-button
'shortdoc-group it)
(shortdoc-function-groups sym)))
(if (= 1 (length groups))
(format "Other relevant functions are documented in the %s group."
(car groups))
(format "Other relevant functions are documented in the %s groups."
(concat (s-join ", " (butlast groups))
" and " (car (last groups))))))))

(defun helpful--make-manual-button (sym)
"Make manual button for SYM."
(helpful--button
Expand Down Expand Up @@ -2261,6 +2292,11 @@ state of the current symbol."
(insert (helpful--format-docstring docstring)))
(when version-info
(insert "\n\n" (s-word-wrap 70 version-info)))
(when (and (symbolp helpful--sym)
helpful--callable-p
(helpful--has-shortdoc-p helpful--sym))
(insert "\n\n")
(insert (helpful--make-shortdoc-sentence helpful--sym)))
(when (and (symbolp helpful--sym) (helpful--in-manual-p helpful--sym))
(insert "\n\n")
(insert (helpful--make-manual-button helpful--sym)))))
Expand Down

0 comments on commit c2729a2

Please sign in to comment.