Function: helpful--signature

helpful--signature is a byte-compiled function defined in helpful.el.

Signature

(helpful--signature SYM)

Documentation

Get the signature for function SYM, as a string.

For example, "(some-func FOO &optional BAR)".

Source Code

;; Defined in ~/.emacs.d/elpa/helpful-20250408.334/helpful.el
;; TODO: this is broken for -any?.
(defun helpful--signature (sym)
  "Get the signature for function SYM, as a string.
For example, \"(some-func FOO &optional BAR)\"."
  (let (docstring-sig
        source-sig
        (advertised-args
         (when (symbolp sym)
           (gethash (symbol-function sym) advertised-signature-table))))
    ;; Get the usage from the function definition.
    (let* ((function-args
            (cond
             ((symbolp sym)
              (help-function-arglist sym))
             ((or (byte-code-function-p sym)
                  (if (fboundp 'interpreted-function-p)
                      (interpreted-function-p sym)))
              ;; argdesc can be a list of arguments or an integer
              ;; encoding the min/max number of arguments. See
              ;; Byte-Code Function Objects in the elisp manual.
              (let ((argdesc (aref sym 0)))
                (if (consp argdesc)
                    argdesc
                  ;; TODO: properly handle argdesc values.
                  nil)))
             (t
              ;; Interpreted function (lambda ...)
              (cadr sym))))
           (formatted-args
            (cond
             (advertised-args
              (-map #'helpful--format-argument advertised-args))
             ((listp function-args)
              (-map #'helpful--format-argument function-args))
             (t
              (list function-args)))))
      (setq source-sig
            (cond
             ;; If it's a function object, just show the arguments.
             ((not (symbolp sym))
              (format "(%s)"
                      (s-join " " formatted-args)))
             ;; If it has multiple arguments, join them with spaces.
             (formatted-args
              (format "(%s %s)"
                      (helpful--format-symbol sym)
                      (s-join " " formatted-args)))
             ;; Otherwise, this function takes no arguments when called.
             (t
              (format "(%s)" (helpful--format-symbol sym))))))

    ;; If the docstring ends with (fn FOO BAR), extract that.
    (-when-let (docstring (documentation sym))
      (-when-let (docstring-with-usage (help-split-fundoc docstring sym))
        (setq docstring-sig (car docstring-with-usage))))

    (cond
     ;; Advertised signature always wins.
     (advertised-args
      source-sig)
     ;; If that's not set, use the usage specification in the
     ;; docstring, if present.
     (docstring-sig
      (replace-regexp-in-string "\\\\=\\(['\\`‘’]\\)" "\\1" docstring-sig t))
     (t
      ;; Otherwise, just use the signature from the source code.
      source-sig))))