Add docstrings to context menu functions, and add middle-separator

* lisp/mouse.el (context-menu-functions): Add context-menu-middle-separator
to default values.
(context-menu-middle-separator): New function.

* lisp/replace.el (occur-context-menu): Use middle-separator.

* lisp/progmodes/elisp-mode.el (elisp-context-menu):
* lisp/progmodes/prog-mode.el (prog-context-menu):
Use middle-separator and reorder menu items correspondingly.

lisp/dired.el

@@ -2194,6 +2194,7 @@ Do so according to the former subdir alist OLD-SUBDIR-ALIST."
      :help "Delete image tag from current or marked files"]))
 
 (defun dired-context-menu (menu click)
+  "Populate MENU with Dired mode commands at CLICK."
   (when (mouse-posn-property (event-start click) 'dired-filename)
     (define-key menu [dired-separator] menu-bar-separator)
     (let ((easy-menu (make-sparse-keymap "Immediate")))

lisp/help-mode.el

@@ -71,6 +71,7 @@
      :help "Customize variable or face"]))
 
 (defun help-mode-context-menu (menu click)
+  "Populate MENU with Help mode commands at CLICK."
   (define-key menu [help-mode-separator] menu-bar-separator)
   (let ((easy-menu (make-sparse-keymap "Help-Mode")))
     (easy-menu-define nil easy-menu nil

lisp/info.el

@@ -4152,6 +4152,7 @@ If FORK is non-nil, it is passed to `Info-goto-node'."
    ["Exit" quit-window :help "Stop reading Info"]))
 
 (defun Info-context-menu (menu click)
+  "Populate MENU with Info commands at CLICK."
   (define-key menu [Info-separator] menu-bar-separator)
   (let ((easy-menu (make-sparse-keymap "Info")))
     (easy-menu-define nil easy-menu nil

lisp/mouse.el

@@ -281,6 +281,7 @@ not it is actually displayed."
 
 (defcustom context-menu-functions '(context-menu-undo
                                     context-menu-region
+                                    context-menu-middle-separator
                                     context-menu-local
                                     context-menu-minor)
   "List of functions that produce the contents of the context menu.
@@ -305,11 +306,19 @@ and should return the same menu with changes such as added new menu items."
   :version "28.1")
 
 (defun context-menu-map (&optional click)
-  "Return composite menu map."
+  "Return menu map constructed for context near mouse CLICK.
+The menu is populated by calling functions from `context-menu-functions'.
+Each function receives the menu and the mouse click event
+and returns the same menu after adding own menu items to the composite menu.
+When there is a text property `context-menu-function' at CLICK,
+it overrides all functions from `context-menu-functions'.
+At the end, it's possible to modify the final menu by specifying
+the function `context-menu-filter-function'."
   (let* ((menu (make-sparse-keymap (propertize "Context Menu" 'hide t)))
          (click (or click last-input-event))
          (fun (mouse-posn-property (event-start click)
                                    'context-menu-function)))
+
     (if (functionp fun)
         (setq menu (funcall fun menu click))
       (run-hook-wrapped 'context-menu-functions
@@ -329,8 +338,14 @@ and should return the same menu with changes such as added new menu items."
       (setq menu (funcall context-menu-filter-function menu click)))
     menu))
 
+(defun context-menu-middle-separator (menu _click)
+  "Add separator to the middle of the context menu.
+Some context functions add menu items below the separator."
+  (define-key-after menu [middle-separator] menu-bar-separator)
+  menu)
+
 (defun context-menu-toolbar (menu _click)
-  "Tool bar menu items."
+  "Populate MENU with submenus from the tool bar."
   (run-hooks 'activate-menubar-hook 'menu-bar-update-hook)
   (define-key-after menu [separator-toolbar] menu-bar-separator)
   (map-keymap (lambda (key binding)
@@ -341,7 +356,7 @@ and should return the same menu with changes such as added new menu items."
   menu)
 
 (defun context-menu-global (menu _click)
-  "Global submenus."
+  "Populate MENU with submenus from the global menu."
   (run-hooks 'activate-menubar-hook 'menu-bar-update-hook)
   (define-key-after menu [separator-global] menu-bar-separator)
   (map-keymap (lambda (key binding)
@@ -352,7 +367,7 @@ and should return the same menu with changes such as added new menu items."
   menu)
 
 (defun context-menu-local (menu _click)
-  "Major mode submenus."
+  "Populate MENU with submenus provided by major mode."
   (run-hooks 'activate-menubar-hook 'menu-bar-update-hook)
   (define-key-after menu [separator-local] menu-bar-separator)
   (let ((keymap (local-key-binding [menu-bar])))
@@ -365,7 +380,7 @@ and should return the same menu with changes such as added new menu items."
   menu)
 
 (defun context-menu-minor (menu _click)
-  "Minor modes submenus."
+  "Populate MENU with submenus provided by minor modes."
   (run-hooks 'activate-menubar-hook 'menu-bar-update-hook)
   (define-key-after menu [separator-minor] menu-bar-separator)
   (dolist (mode (reverse (minor-mode-key-binding [menu-bar])))
@@ -378,7 +393,7 @@ and should return the same menu with changes such as added new menu items."
   menu)
 
 (defun context-menu-buffers (menu _click)
-  "Submenus with buffers."
+  "Populate MENU with the buffer submenus to buffer switching."
   (run-hooks 'activate-menubar-hook 'menu-bar-update-hook)
   (define-key-after menu [separator-buffers] menu-bar-separator)
   (map-keymap (lambda (key binding)
@@ -389,13 +404,13 @@ and should return the same menu with changes such as added new menu items."
   menu)
 
 (defun context-menu-vc (menu _click)
-  "Version Control menu."
+  "Populate MENU with Version Control commands."
   (define-key-after menu [separator-vc] menu-bar-separator)
   (define-key-after menu [vc-menu] vc-menu-entry)
   menu)
 
 (defun context-menu-undo (menu _click)
-  "Undo menu."
+  "Populate MENU with undo commands."
   (define-key-after menu [separator-undo] menu-bar-separator)
   (when (and (not buffer-read-only)
              (not (eq t buffer-undo-list))
@@ -413,7 +428,7 @@ and should return the same menu with changes such as added new menu items."
   menu)
 
 (defun context-menu-region (menu _click)
-  "Region commands menu."
+  "Populate MENU with region commands."
   (define-key-after menu [separator-region] menu-bar-separator)
   (when (and mark-active (not buffer-read-only))
     (define-key-after menu [cut]
@@ -451,26 +466,27 @@ and should return the same menu with changes such as added new menu items."
     (define-key-after menu [clear]
       '(menu-item "Clear" delete-active-region
                   :help
-                  "Delete the text in region between mark and current position")))
+                  "Delete text in region between mark and current position")))
   (define-key-after menu [mark-whole-buffer]
     '(menu-item "Select All" mark-whole-buffer
                 :help "Mark the whole buffer for a subsequent cut/copy"))
   menu)
 
 (defun context-menu-ffap (menu click)
-  "File at point menu."
+  "Populate MENU with commands that find file at point."
   (save-excursion
     (mouse-set-point click)
     (when (ffap-guess-file-name-at-point)
       (define-key menu [ffap-separator] menu-bar-separator)
       (define-key menu [ffap-at-mouse]
         '(menu-item "Find File or URL" ffap-at-mouse
-                    :help "Find file or URL guessed from text around mouse click"))))
+                    :help "Find file or URL from text around mouse click"))))
   menu)
 
 (defvar context-menu-entry
   `(menu-item ,(purecopy "Context Menu") ignore
-              :filter (lambda (_) (context-menu-map))))
+              :filter (lambda (_) (context-menu-map)))
+  "Menu item that creates the context menu and can be bound to a mouse key.")
 
 (defvar context-menu-mode-map
   (let ((map (make-sparse-keymap)))

lisp/net/dictionary.el

@@ -1376,7 +1376,7 @@ any buffer where (dictionary-tooltip-mode 1) has been called."
     (dictionary-search word)))
 
 (defun context-menu-dictionary (menu click)
-  "Dictionary context menu."
+  "Populate MENU with dictionary commands at CLICK."
   (when (thing-at-mouse click 'word)
     (define-key menu [dictionary-separator] menu-bar-separator)
     (define-key menu [dictionary-search-word-at-mouse]

lisp/net/eww.el

@@ -1027,6 +1027,7 @@ the like."
     map))
 
 (defun eww-context-menu (menu click)
+  "Populate MENU with eww commands at CLICK."
   (define-key menu [eww-separator] menu-bar-separator)
   (let ((easy-menu (make-sparse-keymap "Eww")))
     (easy-menu-define nil easy-menu nil

lisp/net/goto-addr.el

@@ -125,6 +125,7 @@ will have no effect.")
   "Keymap to hold goto-addr's mouse key defs under highlighted URLs.")
 
 (defun goto-address-context-menu (menu click)
+  "Populate MENU with goto-address commands at CLICK."
   (when (mouse-posn-property (event-start click) 'goto-address)
     (define-key menu [goto-address-separator] menu-bar-separator)
     (define-key menu [goto-address-at-mouse]

lisp/progmodes/elisp-mode.el

@@ -154,23 +154,24 @@ All commands in `lisp-mode-shared-map' are inherited by this map.")
      :selected (bound-and-true-p eldoc-mode)]))
 
 (defun elisp-context-menu (menu click)
+  "Populate MENU with symbol help commands at CLICK."
   (when (thing-at-mouse click 'symbol)
     (define-key-after menu [elisp-separator] menu-bar-separator
-      'mark-whole-buffer)
+      'middle-separator)
+    (define-key-after menu [info-lookup-symbol]
+      '(menu-item "Look up Symbol"
+                  (lambda (click) (interactive "e")
+                    (info-lookup-symbol
+                     (intern (thing-at-mouse click 'symbol t))))
+                  :help "Display definition in relevant manual")
+      'elisp-separator)
     (define-key-after menu [describe-symbol]
       '(menu-item "Describe Symbol"
                   (lambda (click) (interactive "e")
                     (describe-symbol
                      (intern (thing-at-mouse click 'symbol t))))
                   :help "Display the full documentation of symbol")
-      'elisp-separator)
-    (define-key-after menu [info-lookup-symbol]
-      '(menu-item "Lookup Symbol"
-                  (lambda (click) (interactive "e")
-                    (info-lookup-symbol
-                     (intern (thing-at-mouse click 'symbol t))))
-                  :help "Display definition in relevant manual")
-      'describe-symbol))
+      'elisp-separator))
   menu)
 
 (defun emacs-lisp-byte-compile ()

lisp/progmodes/prog-mode.el

@@ -44,16 +44,14 @@
                                 prettify-symbols-mode))
 
 (defun prog-context-menu (menu click)
+  "Populate MENU with xref commands at CLICK."
   (require 'xref)
   (define-key-after menu [prog-separator] menu-bar-separator
-    'mark-whole-buffer)
-  (when (save-excursion
-          (mouse-set-point click)
-          (xref-backend-identifier-at-point
-           (xref-find-backend)))
-    (define-key-after menu [xref-find-def]
-      '(menu-item "Find Definition" xref-find-definitions-at-mouse
-                  :help "Find definition of identifier")
+    'middle-separator)
+  (when (not (xref-marker-stack-empty-p))
+    (define-key-after menu [xref-pop]
+      '(menu-item "Back Definition" xref-pop-marker-stack
+                  :help "Back to the position of the last search")
       'prog-separator))
   (when (save-excursion
           (mouse-set-point click)
@@ -62,12 +60,15 @@
     (define-key-after menu [xref-find-ref]
       '(menu-item "Find References" xref-find-references-at-mouse
                   :help "Find references to identifier")
-      'xref-find-def))
-  (when (not (xref-marker-stack-empty-p))
-    (define-key-after menu [xref-pop]
-      '(menu-item "Back Definition" xref-pop-marker-stack
-                  :help "Back to the position of the last search")
-      'xref-find-ref))
+      'prog-separator))
+  (when (save-excursion
+          (mouse-set-point click)
+          (xref-backend-identifier-at-point
+           (xref-find-backend)))
+    (define-key-after menu [xref-find-def]
+      '(menu-item "Find Definition" xref-find-definitions-at-mouse
+                  :help "Find definition of identifier")
+      'prog-separator))
   menu)
 
 (defvar prog-mode-map

lisp/replace.el

@@ -2380,13 +2380,13 @@ See also `multi-occur'."
     (occur (concat "\\_<" (regexp-quote symbol) "\\_>"))))
 
 (defun occur-context-menu (menu click)
-  "Populate MENU with occur commands for CLICK.
+  "Populate MENU with occur commands at CLICK.
 To be added to `context-menu-functions'."
   (let ((word (thing-at-mouse click 'word))
         (sym (thing-at-mouse click 'symbol)))
     (when (or word sym)
       (define-key-after menu [occur-separator] menu-bar-separator
-        'mark-whole-buffer)
+        'middle-separator)
       (when sym
         (define-key-after menu [occur-symbol-at-mouse]
           '(menu-item "Occur Symbol" occur-symbol-at-mouse)