;;; my-describe-symbol-at-point.el --- Describe variable or function at point -*- lexical-binding: t; -*-

describe-elisp-symbol-at-point.el

;;; describe-symbol-at-point.el --- Describe variable or function at point -*- lexical-binding: t; -*-
;; Description: Clear the contents of the *Messages* buffer if it is the current buffer.
;; Gits URL: https://gist.github.com/jamescherti/abb288cb98f5f9f08431cc29225273fe
;; License: MIT
;; Author: James Cherti

(defun my-describe-elisp-symbol-at-point ()
    "Describe the symbol at point as either a variable or a function.

This function determines whether the symbol at point is a variable or a
function. If the symbol is identified as a function or a variable exclusively,
it will automatically describe it. If both types are detected or neither is
detected, the user is prompted to choose whether to describe it as a variable or
a function.

After describing the symbol, if a help buffer is active, it will rename the help
buffer to include the name of the symbol.

The function displays messages if the symbol at point is not a variable or
function or if an invalid choice is made."
  (interactive)
  (let* ((symbol (symbol-at-point))
         (is-function (and symbol (fboundp symbol)))
         (is-variable (and symbol (boundp symbol)))
         (choice nil))

    ;; Automatically select function or variable if only one is at point,
    ;; otherwise ask the user.
    (cond
     (is-function
      (setq choice ?f))
     (is-variable
      (setq choice ?v))
     (t
      (setq choice (read-char "Describe (v)ariable or (f)unction? "))))

    ;; Handle the chosen option for describing a function or variable.
    (cond
     ((eq choice ?v)
      (describe-variable symbol))
     ((eq choice ?f)
      (describe-function symbol))
     ((not choice)
      (message "No function or variable at point."))
     (t
      (message
       "Invalid choice, press 'v' for variable or 'f' for function.")))

    (when (or (eq choice ?v)
              (eq choice ?f))
      (let ((help-buffer (get-buffer "*Help*")))
        (when help-buffer
          (with-current-buffer help-buffer
            (rename-buffer
             (format "*Help:%s*" (symbol-name symbol)) t)))))))