[elpa] externals/cpupower db7bf2406c 12/35: a bit more

[ELPA Syncer]

branch: externals/cpupower
commit db7bf2406c5ed628ea7ec9f5ffe54eb8d301c2a0
Author: smeister <smeister@awstruepower.com>
Commit: smeister <smeister@awstruepower.com>

    a bit more
---
 cpupower.el | 54 ++++++++++++++++++++++++++++++++++++++----------------
 1 file changed, 38 insertions(+), 16 deletions(-)

diff --git a/cpupower.el b/cpupower.el
index 9eef3d41a9..edd5bb4aed 100644
--- a/cpupower.el
+++ b/cpupower.el
@@ -19,7 +19,13 @@
 ;;; Commentary
 
 ;; If you have cpupower installed, this provides a very simple wrapper
-;; to that program.
+;; to that program.  You'll need to configure your system such that
+;; the user you're using emacs as can run cpupower (probably as `sudo
+;; cpupower` from a command line).  You can configure how cpupower is
+;; called by customizing cpupower-cmd.
+;;
+;; This module interacts with cpupower via running it in a shell.
+;; 
 ;;
 ;; The commands you'll probably want to use:
 ;; * cpupower-info
@@ -35,27 +41,32 @@
 ;; * cpupower-get-current-governors
 ;;   - returns a list of all cpu governors by core.
 
-
+;;; Code:
 ;; pretty sure I don't need this, but?
 (setq lexical-binding t)
 
-(defconst cpupower-cmd
+(defcustom cpupower-cmd
   "sudo cpupower"
-  "cpupower command, might need a 'sudo' infront of it")
+  "cpupower command, might need a 'sudo' infront of it and you
+might need to enable this command for your user in /etc/sudoers"
+  :type '(string)
+  :group 'cpupower)
 
 (defconst cpupower--compatible-versions
   '("5.4")
-  "Versions of cpupower which cpupower.el can work with")
+  "Versions of cpupower which cpupower.el can work with.")
 
 (defvar cpupower--info
   nil
   "Where cached information about cpupower will be put")
 
 (defmacro cpupower--with-cache-slot (cache-slot-name deriving-sexp)
-  "Get something from cache or derive it and populate cache.
+  "Get something from cache (cpupower--info) or derive it and populate cache.
 
-This macro isn't strictly needed but I kinda wanted to practice
-writing macros.  So here we are."
+CACHE-SLOT-NAME is the key under which the result is stored.
+
+DERIVING-SEXP is a single sexp which should return the value.  It
+will be called if the value is not cached."
   (declare (indent 1))
   `(let ((cached-value (plist-get cpupower--info ,cache-slot-name)))
      (if cached-value
@@ -88,7 +99,9 @@ TODO: do this in a less bad way?"
       cpu-count)))
 
 (defun cpupower--get-available-governors ()
-  "Get a list of all valid governors for this system."
+  "Get a list of all valid governors for this system.
+
+@todo - this should be done using cpupower? not cat-ing some random file."
   (cpupower--with-cache-slot :governors
     (let ((governors-per-cpu))
       (cl-loop for cpu-num in (number-sequence 0 (cpupower--get-num-cpus))
@@ -106,7 +119,7 @@ TODO: do this in a less bad way?"
                finally return valid-governors))))
 
 (defun cpupower--run (subcommand)
-  "Execute cpupower with SUBCOMMAND string."
+  "Execute cpupower with SUBCOMMAND arguments return the output as a string."
   (with-temp-buffer
     (let ((command (format "%s %s" cpupower-cmd subcommand)))
       (message "running: %s" command)
@@ -114,7 +127,7 @@ TODO: do this in a less bad way?"
       (buffer-string))))
 
 (defun cpupower--format-KHz (KHz)
-  "Format KHz for human eyes (probably translating to MHz or GHz)."
+  "Format KHZ (as KHz) for human eyes (probably translating to MHz or GHz)."
   (cond ((> KHz 1000000)
          (format "%.2fGHz" (/ KHz 1000000.0)))
         ((> KHz 1000)
@@ -149,7 +162,10 @@ function returns: (\"and\" \"too\")
            finally return output-tokens))
 
 (defun cpupower-info ()
-  "Place current cpupower information into the message buffer."
+  "Place current cpupower information into the message buffer.
+
+This is indented as the primary way for humans to see this
+information."
   (interactive)
   (let ((governors (seq-uniq (cpupower-get-current-governors) 'string-equal))
         (frequencies (mapcar 'cpupower--format-KHz 
(cpupower-get-current-frequencies))))
@@ -159,7 +175,7 @@ function returns: (\"and\" \"too\")
              (cpupower--get-version))))
 
 (defun cpupower-set-governor (governor)
-  "Set the governor on all CPUs to a given governor by name (string)."
+  "Set the governor on all CPUs to a given GOVERNOR by name (string)."
   (interactive "sGovernor: ")
   (let ((valid-governors (cpupower--get-available-governors)))
     (unless (member governor valid-governors)
@@ -168,7 +184,10 @@ function returns: (\"and\" \"too\")
     (cpupower-info)))
 
 (defun cpupower-get-current-frequencies (&optional print-message)
-  "Return a list of CPU frequencies in KHz"
+  "Return a list of CPU frequencies in KHz
+
+When called interactively (PRINT-MESSAGE will be true) it will
+message the user with current CPU frequencies."
   (interactive "p")
   (let* ((output (cpupower--run "--cpu all frequency-info -f"))
          (frequencies (mapcar 'string-to-number
@@ -179,7 +198,10 @@ function returns: (\"and\" \"too\")
     frequencies))
 
 (defun cpupower-get-current-governors (&optional print-message)
-  "Return a list of CPU governors"
+  "Return a list of CPU governors
+
+When called interactively (PRINT-MESSAGE will be true) it will
+message the user with current CPU governors"
   (interactive "p")
   (let* ((output (cpupower--run "--cpu all frequency-info -p"))
          (governors (mapcar (lambda (quoted)
@@ -193,7 +215,7 @@ function returns: (\"and\" \"too\")
     governors))
 
 (defun cpupower-helm-set-governor ()
-  "Set cpu governor using helm
+  "Set cpu governor using helm.
 
 @TODO - this should only exist when helm is installed?"
   (interactive)