[nongnu] elpa/opam-switch-mode e2ed274519 05/31: add emacs code documentation, also delete default switch parsing

[ELPA Syncer]

branch: elpa/opam-switch-mode
commit e2ed274519aaed89c732284823921d795bdbed73
Author: Hendrik Tews <Hendrik.Tews@kernkonzept.com>
Commit: Hendrik Tews <Hendrik.Tews@kernkonzept.com>

    add emacs code documentation, also delete default switch parsing
---
 opam-mode.el | 106 ++++++++++++++++++++++++++++++++++++++++++++++++-----------
 1 file changed, 87 insertions(+), 19 deletions(-)

diff --git a/opam-mode.el b/opam-mode.el
index 9b42e090da..ccaf7a5c7d 100644
--- a/opam-mode.el
+++ b/opam-mode.el
@@ -41,17 +41,36 @@
 
 ;;; User options and variables
 
+(defgroup opam-mode ()
+  "Customization for opam switch support in Emacs"
+  :group 'external)
+
+  
 (defcustom opam-program-name "opam"
-  "XXX")
+  "Name or path of the opam binary."
+  :group 'opam-mode
+  :type 'string)
 
 (defcustom opam-common-options ()
-  "XXX")
+  "Options to be supplied to every opam invocation.
+This must be a list of strings, each member string an option
+accepted by opam."
+  :group 'opam-mode
+  :type '(repeat string))
 
 (defcustom opam-common-environment
   '("OPAMUTF8=never"
     "OPAMCOLOR=never"
     "LC_ALL=C")
-  "XXX")
+  "Process environment to be set for every opam invocation.
+List of strings compatible with `process-environment', i.e., each
+element should have the form of ENVVARNAME=VALUE.
+
+The process environment must ensure that output is plain ascii
+without color, non-ascii arrow symbols and that it is in English.
+Otherwise parsing the output of opam commands won't work."
+  :group 'opam-mode
+  :type '(repeat string))
 
 
 ;;; Code
@@ -59,7 +78,16 @@
 (defun opam-run-command-without-stderr (sub-cmd
                                         &optional switch sexp
                                         &rest args)
-  "XXX"
+  "Run opam SUB-CMD, without capturing error output.
+Run opam SUB-CMD with additional arguments and insert the output
+in the current buffer at point. Error output (stderr) is
+discarded. If SWITCH is not nil, an option \"--swith=SWITCH\" is
+added. If SEXP is t, option --sexep is added. All remaining
+arguments ARGS are added as arguments.
+
+Internally this function uses `process-file' internally and will
+therfore respect file-name handlers specified via
+`default-directory'."
   (let ((process-environment
          (append opam-common-environment process-environment))
         (options (append args opam-common-options)))
@@ -72,20 +100,26 @@
                nil '(t nil) nil sub-cmd options)))
 
 (defun opam-command-as-string (sub-cmd &optional switch sexp &rest args)
-  "XXX"
+  "Return output of opam SUB-CMD as string.
+Same as `opam-run-command-without-stderr' but return all output
+as string."
   (with-temp-buffer
     (apply 'opam-run-command-without-stderr sub-cmd switch sexp args)
     (buffer-string)))
 
 (defun opam-get-root ()
+  "Get the opam root directory.
+This is the opam variable 'root'."
   (let ((root (opam-command-as-string "var" nil nil "root")))
     (when (eq (aref root (1- (length root))) ?\n)
       (setq root (substring root 0 -1)))
     root))
 
 (defconst opam-root (opam-get-root)
-  "XXX")
+  "The opam root directory.")
 
+;; Example output of opam switch. The warning is output on stderr.
+;;
 ;; OPAMUTF8=never OPAMCOLOR=never LC_ALL=C opam switch
 ;; #   switch        compiler                       description
 ;; ->  4112-coq-812  ocaml-variants.4.11.2+flambda  4112-coq-812
@@ -101,37 +135,53 @@
 ;;           You should run: eval $(opam env)
 
 (defun opam-get-switches ()
-  ""
+  "Return all opam switches as list of strings."
   (let (opam-switches)
     (with-temp-buffer
       (opam-run-command-without-stderr "switch")
       (goto-char (point-min))
       (forward-line)
-      (while (re-search-forward "^\\(..\\) *\\([^ ]*\\).*$" nil t)
-        (push (match-string 2) opam-switches)
-        (when (equal (match-string 1) "->")
-          (setq default-switch (match-string 2))))
+      (while (re-search-forward "^.. *\\([^ ]*\\).*$" nil t)
+        (push (match-string 1) opam-switches))
       opam-switches)))
 
 (defvar opam-switch-history nil
-  "XXX")
+  "Minibuffer history list for `opam-set-switch'.")
 
 (defvar opam-saved-env nil
-  "XXX")
+  "Saved environment variables, overwritten by an opam switch.
+This is a list of saved environment variables. Each saved
+variable is a list of two strings, the variable and the value.
+Set when the first chosen opam switch overwrites the
+environment.")
 
 (defvar opam-saved-exec-path nil
-  "XXX")
+  "Saved value of `exec-path'.
+Set when the first chosen opam switch overwrites `exec-path'.")
 
 
 (defun opam-save-current-env (opam-env)
-  "XXX"
+  "Save the current environment values relevant to opam.
+Argument OPAM-ENV, coming from calling `opam env', is only used
+to find the environment variables to save. `exec-path' is saved
+in addition to environment variables."
   (setq opam-saved-env
        (mapcar (lambda (x) (list (car x) (getenv (car x)))) opam-env))
   (setq opam-saved-exec-path exec-path))
   
-
 (defun opam-set-env (opam-env)
-  "XXX"
+  "Sets a new opam environment.
+Environment variables in OPAM-ENV are put into the environment of
+the current Emacs session. `exec-path' is changed to match the
+environment PATH.
+
+It is unclear which value in `exec-path' corresponds to a
+previously set opam switch and also which entry in the PATH
+environment variable in OPAM-ENV corresponds to the new switch.
+Therefore this function uses the following heuristic. First all
+entries in `exec-path' that match `opam-root' are deleted. Then,
+the first entry for PATH that maches `opam-root' is added at the
+front of `exec-path'."
   (let ((new-bin-dir
          (seq-find
           (lambda (dir) (string-prefix-p opam-root dir))
@@ -144,7 +194,10 @@
     (push new-bin-dir exec-path)))
   
 (defun opam-reset-env ()
-  "XXX"
+  "Reset process environment to the state before setting the first opam switch.
+Reset all environment variables and `exec-path' to the values
+they had in this emacs session before the first chosen opam
+switch overwrote them."
   (mapc (lambda (x) (setenv (car x) (cadr x))) opam-saved-env)
   (setq exec-path opam-saved-exec-path)
   (setq opam-saved-env nil)
@@ -152,7 +205,22 @@
 
 
 (defun opam-set-switch (switch-name)
-  "XXX"
+  "Chose and set an opam switch.
+Set opam swith SWITCH-NAME, which must be a valid opam switch
+name. When called interactively, the switch name must be entered
+in the minibuffer, which forces completion to a valid switch name
+or the empty string.
+
+Setting the opam switch for the first time inside emacs will save
+the current environment. Using the empty string for SWITCH-NAME
+will reset the environment to the saved values.
+
+The switch is set such that all process invocations from
+emacs respect the newly set opam switch. In addition to setting
+environment variables such as PATH and CAML_LD_LIBRARY_PATH, this
+also sets `exec-path', which controls emacs'
+subprocesses (`call-process', `make-process' and similar
+functions)."
   (interactive
    (let* ((switches (opam-get-switches))
           (default (car switches))