diff --git a/helpful.el b/helpful.el index 9516e46..ee878a4 100644 --- a/helpful.el +++ b/helpful.el @@ -2270,6 +2270,11 @@ state of the current symbol." "\n\n" (helpful--format-obsolete-info helpful--sym helpful--callable-p))) + (when (helpful--interactive-only-info helpful--sym) + (insert + "\n\n" + (helpful--format-interactive-only-info helpful--sym))) + (when (and helpful--callable-p (not (helpful--kbd-macro-p helpful--sym))) (helpful--insert-section-break) @@ -2637,6 +2642,29 @@ For example, \"(some-func FOO &optional BAR)\"." (use (format "; use `%s' instead." use)) (t "."))))))) +(defun helpful--interactive-only-info (sym) + "If SYM has the `interactive-only' property, return its value. +Return nil otherwise." + (when (symbolp sym) + (get sym 'interactive-only))) + +(defun helpful--format-interactive-only-info (sym) + "Format a note about SYM being interactive-only." + (let ((alternative (helpful--interactive-only-info sym))) + (helpful--format-docstring + (s-word-wrap + 70 + (cond + ((and (symbolp alternative) (not (eq alternative t))) + (format + "This command is for interactive use only; in Lisp code use `%s' instead." + alternative)) + ((stringp alternative) + (format "This command is for interactive use only; %s" + alternative)) + (t + "This command is for interactive use only.")))))) + (defun helpful--docstring (sym callable-p) "Get the docstring for SYM. Note that this returns the raw docstring, including \\=\\= diff --git a/test/helpful-unit-test.el b/test/helpful-unit-test.el index bdfdfc1..8cd0794 100644 --- a/test/helpful-unit-test.el +++ b/test/helpful-unit-test.el @@ -23,6 +23,24 @@ (declare (obsolete helpful "1.2.3")) nil) +(defun helpful-test-interactive-only-sym () + "A test command that is interactive-only with a symbol alternative." + (interactive) + nil) +(put 'helpful-test-interactive-only-sym 'interactive-only 'helpful-test-fun-obsolete) + +(defun helpful-test-interactive-only-t () + "A test command that is interactive-only with t." + (interactive) + nil) +(put 'helpful-test-interactive-only-t 'interactive-only t) + +(defun helpful-test-interactive-only-str () + "A test command that is interactive-only with a string." + (interactive) + nil) +(put 'helpful-test-interactive-only-str 'interactive-only "use something else in Lisp code.") + (defun test-foo () "Docstring here." nil) @@ -614,6 +632,29 @@ associated a lambda with a keybinding." (should (equal info "This function is obsolete since 1.2.3; use helpful instead.")))) +(ert-deftest helpful--interactive-only-symbol () + "Test display of interactive-only with symbol alternative." + (let ((info (helpful--format-interactive-only-info + 'helpful-test-interactive-only-sym))) + (should + (equal info + "This command is for interactive use only; in Lisp code use\nhelpful-test-fun-obsolete instead.")))) + +(ert-deftest helpful--interactive-only-t () + "Test display of interactive-only with t." + (let ((info (helpful--format-interactive-only-info + 'helpful-test-interactive-only-t))) + (should + (equal info "This command is for interactive use only.")))) + +(ert-deftest helpful--interactive-only-string () + "Test display of interactive-only with string." + (let ((info (helpful--format-interactive-only-info + 'helpful-test-interactive-only-str))) + (should + (equal info + "This command is for interactive use only; use something else in Lisp\ncode.")))) + (ert-deftest helpful--keymap-keys--sparse () (let* ((parent-keymap (make-sparse-keymap)) (keymap (make-sparse-keymap)))