docs(core): better documentation and comments

Author: abougouffa

elisp/ecryptfs.el

@@ -1,4 +1,4 @@
-;; -*- lexical-binding: t; -*-
+;; ecryptfs.el -- eCryptfs integration -*- lexical-binding: t; -*-
 
 ;; Copyright (C) 2022-2023  Abdelhak Bougouffa
 
@@ -8,19 +8,20 @@
 
 ;; This allows me to mount my private directory encrypted using ecryptfs-utils.
 ;; It is a port of "ecryptfs-mount-private" shell command. It extracts the
-;; encryption key from a GPG encrypted file containting the ecryptfs password.
+;; encryption key from a GPG encrypted file containing the eCryptfs password.
 ;; The decryption of the password is performed using Emacs' `epg'.
 
 ;;; Code:
 
 (require 'epg)
+(autoload 'cl-every "cl-extras")
 
 (defgroup minemacs-ecryptfs nil
   "MinEmacs eCryptfs."
   :group 'minemacs)
 
 (defcustom ecryptfs-private-dir-name "Private"
-  "eCryptfs private directory name."
+  "The eCryptfs private directory name."
   :group 'minemacs-ecryptfs
   :type 'string)
 
@@ -29,21 +30,26 @@
   :group 'minemacs-ecryptfs
   :type 'directory)
 
-(defcustom ecryptfs-passphrase-file (concat ecryptfs-root-dir "my-pass.gpg")
-  "GPG encrypted file containing eCryptfs password.")
+(defcustom ecryptfs-passphrase-file (concat ecryptfs-root-dir "password.gpg")
+  "GPG encrypted file containing eCryptfs password."
+  :group 'minemacs-ecryptfs
+  :type 'file)
 
 (defvar ecryptfs-buffer-name " *emacs-ecryptfs*")
 (defvar ecryptfs-process-name "emacs-ecryptfs")
 (defvar ecryptfs--mount-private-cmd "/sbin/mount.ecryptfs_private")
 (defvar ecryptfs--umount-private-cmd "/sbin/umount.ecryptfs_private")
 
 (defun ecryptfs--wrapped-passphrase-file ()
+  "Return eCryptfs' wrapped passphrase file path."
   (concat ecryptfs-root-dir "wrapped-passphrase"))
 
 (defun ecryptfs--mount-passphrase-sig-file ()
+  "Return eCryptfs' wrapped passphrase signature file path."
   (concat ecryptfs-root-dir ecryptfs-private-dir-name ".sig"))
 
 (defun ecryptfs--passphrase ()
+  "Return eCryptfs' passphrase from the GPG encrypted password file."
   (string-trim-right
    (epg-decrypt-file
     (epg-make-context)
@@ -52,25 +58,29 @@
    "[\n\r]+"))
 
 (defun ecryptfs--encrypt-filenames-p ()
+  "Des eCryptfs is configured with encrypted file names."
   (/= 1 (with-temp-buffer
           (insert-file-contents (ecryptfs--mount-passphrase-sig-file))
           (count-lines (point-min) (point-max)))))
 
 (defun ecryptfs-available-p ()
+  "Is eCryptfs available on the current system?"
   (and (file-directory-p (expand-file-name ecryptfs-private-dir-name "~"))
        (cl-every #'file-exists-p (list ecryptfs--mount-private-cmd
                                        ecryptfs--umount-private-cmd
                                        (ecryptfs--wrapped-passphrase-file)
                                        (ecryptfs--mount-passphrase-sig-file)))))
 
 (defun ecryptfs--unwrap-passphrase-command ()
+  "Return eCryptfs' command that unwraps the passphrase."
   (format
    (if (ecryptfs--encrypt-filenames-p)
        "ecryptfs-insert-wrapped-passphrase-into-keyring %s '%s'"
      "ecryptfs-unwrap-passphrase %s '%s' | ecryptfs-add-passphrase -")
    (ecryptfs--wrapped-passphrase-file) (ecryptfs--passphrase)))
 
 (defun ecryptfs-private-mounted-p ()
+  "Is eCryptfs' private directory is mounted?"
   (let ((mount (shell-command-to-string "mount")))
     (and (string-match-p (concat ".*" (expand-file-name ecryptfs-private-dir-name "~") ".*ecryptfs.*") mount)
          t)))
@@ -100,7 +110,7 @@
               (prog1 try-again (setq try-again nil)))
         (if (zerop (shell-command (ecryptfs--unwrap-passphrase-command) ecryptfs-buffer-name))
             (message "Successfully mounted private directory.")
-          (user-error "A problem occured while mounting the private directory, see %s"
+          (user-error "A problem occurred while mounting the private directory, see %s"
                       ecryptfs-buffer-name))))))
 
 ;;;###autoload

elisp/netextender.el

@@ -31,7 +31,7 @@ mandatory stored as a GPG encrypted file."
   :group 'minemacs-netextender
   :type '(choice string file))
 
-(defcustom netextender-launcher-command (concat minemacs-local-dir "netextender-launcher.sh")
+(defcustom netextender-launcher-command (locate-user-emacs-file "netextender-launcher.sh")
   "Custom NetExtender launcher command.
 
 This is a wrapper around the \"NetExtender\" command. It starts the sessions
@@ -50,19 +50,18 @@ temporary based on `netextender-command' and `netextender-passphrase-file' and
 returns it."
   ;; If the command doesn't exist, generate it.
   (if (not (executable-find netextender-command))
-      (user-error "The NetExtender command \"%s\" is not available." netextender-command)
+      (user-error "The NetExtender command \"%s\" is not available" netextender-command)
     (unless (executable-find netextender-launcher-command)
       (setq netextender-launcher-command (make-temp-file "netextender-launcher-" nil ".sh"))
       (set-file-modes netextender-launcher-command #o755) ;; Make it executable
-      (with-temp-buffer
-        (insert (format "#!/bin/bash
+      (with-temp-buffer (insert (format "#!/bin/bash
 
 MY_LOGIN_PARAMS_FILE=\"%s\"
 
 echo \"Y\\n\" | %s --auto-reconnect $(gpg -q --for-your-eyes-only --no-tty -d \"${MY_LOGIN_PARAMS_FILE}\")"
-                        (expand-file-name netextender-passphrase-file)
-                        (executable-find netextender-command)))
-        (write-file netextender-launcher-command)))
+                                        (expand-file-name netextender-passphrase-file)
+                                        (executable-find netextender-command)))
+                        (write-file netextender-launcher-command)))
     ;; Return the command
     netextender-launcher-command))
 
@@ -73,7 +72,7 @@ echo \"Y\\n\" | %s --auto-reconnect $(gpg -q --for-your-eyes-only --no-tty -d \"
     ;; pppd must be run as root (via setuid)
     (if (and pppd-modes (zerop (logand (lsh 1 11) pppd-modes))) ;; Check if the setuid bit isn't set
         (prog1 nil ;; return nil
-          (user-error "pppd needs root permissions, please set the setuid bit of %s." pppd-command))
+          (user-error "The `pppd' command needs root permissions, please set the setuid bit of %s" pppd-command))
       t)))
 
 ;;;###autoload
@@ -86,8 +85,8 @@ echo \"Y\\n\" | %s --auto-reconnect $(gpg -q --for-your-eyes-only --no-tty -d \"
                           :buffer netextender-buffer-name
                           :command (list (netextender-launcher-command)))
             (message "Started NetExtender VPN session.")
-          (user-error "Cannot start NetExtender.")))
-    (user-error "Cannot start a netExtender VPN session.")))
+          (user-error "Cannot start NetExtender")))
+    (user-error "Cannot start a netExtender VPN session")))
 
 (defun netextender-kill ()
   "Kill the created NetExtender VPN session."
@@ -96,7 +95,7 @@ echo \"Y\\n\" | %s --auto-reconnect $(gpg -q --for-your-eyes-only --no-tty -d \"
     (if netextender-process
         (if (kill-process netextender-process)
             (message "Killed NetExtender VPN session.")
-          (user-error "Cannot kill NetExtender."))
+          (user-error "Cannot kill NetExtender"))
       (message "No running NetExtender session."))))
 
 ;;;###autoload

elisp/valgrind.el

@@ -9,21 +9,23 @@
 ;;; Code:
 
 (require 'compile)
+(require 'project)
+(eval-when-compile (require 'savehist))
 
 (defgroup valgrind nil
   "Run valgrind as inferior of Emacs, parse error messages."
   :group 'tools
   :group 'processes)
 
 (defcustom valgrind-command "valgrind --leak-check=full "
-  "*Last shell command used to run valgrind; default for next valgrind run.
+  "Last shell command used to run valgrind; default for next valgrind run.
 Sometimes it is useful for files to supply local values for this variable.
 You might also use mode hooks to specify it in certain modes, like this:
-  (add-hook 'c-mode-hook
+  (add-hook \\='c-mode-hook
     (lambda ()
       (unless (or (file-exists-p \"makefile\")
                   (file-exists-p \"Makefile\"))
-        (set (make-local-variable 'valgrind-command)
+        (set (make-local-variable \\='valgrind-command)
              (concat \"make -k \"
                      (file-name-sans-extension buffer-file-name))))))"
   :type 'string
@@ -39,10 +41,10 @@ You might also use mode hooks to specify it in certain modes, like this:
 ;;;###autoload
 (defun valgrind (command)
   "Run valgrind.
-Runs COMMAND, a shell command, in a separate process asynchronously
-with output going to the buffer `*valgrind*'.
-You can then use the command \\[next-error] to find the next error message
-and move to the source code that caused it."
+Runs a shell COMMAND in a separate process asynchronously with output going to
+the buffer `*valgrind*'.
+You can then use the command \\[next-error] to find the next error message and
+move to the source code that caused it."
   (interactive
    (if (or compilation-read-command current-prefix-arg)
        (list (read-from-minibuffer "Valgrind command: "
@@ -52,7 +54,7 @@ and move to the source code that caused it."
   (let ((default-directory (or (project-root (project-current)) default-directory)))
     (unless (equal command (eval valgrind-command))
       (setq valgrind-command command))
-    (compilation-start command nil (lambda (mode) "*valgrind*"))))
+    (compilation-start command nil (lambda (_) "*valgrind*"))))
 
 
 (provide 'valgrind)

init.el

@@ -114,14 +114,14 @@
 ;; some new features when configuring them.
 (when (< emacs-major-version 29)
   (let ((backports-dir (concat minemacs-core-dir "backports/")))
-    (mapc (apply-partially #'+load backports-dir) (directory-files backports-dir nil "\\.el$"))))
+    (mapc (apply-partially #'+load backports-dir) (directory-files backports-dir nil "\\.el\\'"))))
 
 (setq
  ;; Enable debugging on error when Emacs is launched with the "--debug-init"
  ;; option or when the environment variable "$MINEMACS_DEBUG" is defined (see
  ;; `me-vars').
  debug-on-error minemacs-debug-p
- ;; Decrese the warning type to `:error', unless we are running in verbose mode
+ ;; Decrease the warning type to `:error', unless we are running in verbose mode
  warning-minimum-level (if minemacs-verbose-p :warning :error)
  warning-minimum-log-level warning-minimum-level
  ;; Make byte compilation less noisy