update eglot-server-programs customization widget

add inline widget documentation
define constants for widget formats
revise :type for TCP Connection
rename TCP Auto-connect to TCP Auto-Launch

Author: lmmarsano

eglot.el

@@ -78,23 +78,37 @@
   :prefix "eglot-"
   :group 'applications)
 
+(defconst eglot-custom-format-doc "%t: %v%h"
+  "Custom type format for widget with expandable inline documentation.")
+
+(defconst eglot-custom-format-button-doc "%[%t%] %v%h"
+  "Custom type format for button widget with expandable inline documentation.")
+
 (defconst eglot-server-programs-contact
-  '((cons :tag "Standard I/O"
+  `((cons :format ,eglot-custom-format-doc
+          :tag "Standard I/O"
+          :doc "PROGRAM is called with ARGS and is expected to serve LSP requests over the standard input/output channels."
           (string :tag "Program")
           (repeat :tag "Arguments" string))
-    (list :tag "TCP Connection"
-          (string :tag "Host")
-          (number :tag "Port")
-          (list :tag "TCP Arguments"
-                :inline t
-                string
-                (choice (const nil)
-                        string)
-                string
-                (choice string
-                        number)
-                (plist :key-type symbol)))
-    (cons :tag "TCP Auto-connect"
+    (list :format ,eglot-custom-format-doc
+          :tag "TCP Connection"
+          :doc "For connecting to a server via TCP."
+          (string :format ,eglot-custom-format-doc
+                  :tag "Host"
+                  :doc "Name or IP address.")
+          (number :tag "TCP Port")
+          (plist :format ,eglot-custom-format-doc
+                 :tag "TCP Parameters"
+                 :doc "Passed to `open-network-stream' for upgrading the connection with encryption or other capabilities.
+Sequence of keywords and values: consult `open-network-stream' PARAMETERS documentation."
+                 :key-type (symbol :tag "Keyword")))
+    (cons :format ,eglot-custom-format-doc
+          :tag "TCP Auto-Launch"
+          :doc "A combination of TCP Connection and program launch.
+First, an attempt is made to find an available server port, then
+PROGRAM is launched with ARGS; the `:autoport' keyword substituted for
+that number; and MOREARGS. Eglot then attempts to to establish a TCP
+connection to that port number on the localhost."
           (string :tag "Program")
           (list (repeat :tag "Arguments"
                         :inline t
@@ -173,12 +187,29 @@ of those modes.  CONTACT can be:
                 :value-type (choice :tag "Contact"
                                     ,@eglot-server-programs-contact
                                     (cons :tag "Experimental LSP"
-                                          (symbol :tag "Class Name")
-                                          (choice :tag "Initialization"
-                                                  (plist :tag "Class Initializer"
+                                          (symbol :format ,eglot-custom-format-doc
+                                                  :tag "Class Name"
+                                                  :doc "A symbol designating a subclass of `eglot-lsp-server', for representing experimental LSP servers.")
+                                          (choice :format ,eglot-custom-format-button-doc
+                                                  :tag "Initialization"
+                                                  :doc "A plist of CLASS-NAME initialization parameters, or a CONTACT form, which is converted to a suitable :PROCESS initialization parameter for CLASS-NAME.
+The class `eglot-lsp-server' descends `jsonrpc-process-connection',
+which you should see for the semantics of the mandatory :PROCESS
+argument."
+                                                  (plist :format ,eglot-custom-format-doc
+                                                         :tag "Class Initializer"
+                                                         :doc "A keyword-value plist used to initialize CLASS-NAME."
                                                          :key-type symbol)
                                                   ,@eglot-server-programs-contact))
-                                    (function :tag "Contact Generator"))))
+                                    (function :format ,eglot-custom-format-doc
+                                              :tag "Contact Generator"
+                                              :doc "A function of a single argument producing any of the other values for CONTACT.
+The argument's value is non-nil if the connection was requested
+interactively (e.g. from the `eglot' command), and nil if it wasn't
+(e.g. from `eglot-ensure'). If the call is interactive, the function
+can ask the user for hints on finding the required programs, etc.
+Otherwise, it should not ask the user for any input, and return nil or
+signal an error if it can't produce a valid CONTACT."))))
 
 (defface eglot-mode-line
   '((t (:inherit font-lock-constant-face :weight bold)))