31 files changed, 205 insertions, 13 deletions
diff --git a/init.el b/init.el
index 0a97787..875ac87 100644
--- a/init.el
+++ b/init.el
@@ -1,3 +1,7 @@
+;;; init.el --- load the configuration
+;;; Commentary:
+;;; Code:
+
 ;; configure load paths
 (let ((lisp-directory (expand-file-name "lisp" user-emacs-directory)))
   ;; add ~/.emacs.d/lisp to load path
@@ -6,7 +10,7 @@
   ;; save customizations as local (unversioned) settings
   (setq custom-file (expand-file-name "init-local.el" lisp-directory)))
 
-;; packages
+;; package management
 (require 'init-package)
 
 ;; local settings (optional)
@@ -55,3 +59,7 @@
 (mpolden/maybe-require 'init-python)
 (mpolden/maybe-require 'init-rust)
 (mpolden/maybe-require 'init-yaml)
+
+(provide 'init)
+
+;;; init.el ends here
diff --git a/lisp/init-amx.el b/lisp/init-amx.el
index adf44b8..f10ad03 100644
--- a/lisp/init-amx.el
+++ b/lisp/init-amx.el
@@ -1,4 +1,7 @@
-;; enable amx-mode for smarter candidates in M-x
+;;; init-amx.el --- configure a better M-x
+;;; Commentary:
+;;; Code:
+
 (use-package amx
   :ensure t
   :after ivy
@@ -6,3 +9,5 @@
   (amx-mode 1))
 
 (provide 'init-amx)
+
+;;; init-amx.el ends here
diff --git a/lisp/init-appearance.el b/lisp/init-appearance.el
index e81b208..af36214 100644
--- a/lisp/init-appearance.el
+++ b/lisp/init-appearance.el
@@ -1,3 +1,7 @@
+;;; init-appearance.el --- configure appearance
+;;; Commentary:
+;;; Code:
+
 ;; disable splash
 (setq inhibit-startup-message t)
 
@@ -29,8 +33,8 @@
 ;; highlight trailing whitespace in prog-mode
 (add-hook 'prog-mode-hook (lambda () (setq-local show-trailing-whitespace t)))
 
-;; render ansi colors in compilation buffer
 (defun mpolden/colorize-compilation-buffer ()
+  "Render ansi colors in compilation buffer."
   (when (eq major-mode 'compilation-mode)
     (ansi-color-apply-on-region compilation-filter-start (point-max))))
 
@@ -45,3 +49,5 @@
       column-number-mode t)
 
 (provide 'init-appearance)
+
+;;; init-appearance.el ends here
diff --git a/lisp/init-dired.el b/lisp/init-dired.el
index 2131c8f..a83fa7a 100644
--- a/lisp/init-dired.el
+++ b/lisp/init-dired.el
@@ -1,3 +1,7 @@
+;;; init-dired.el --- configure dired
+;;; Commentary:
+;;; Code:
+
 (use-package dired
   :init
   ;; show human readable sizes in dired and sort dotfiles first
@@ -16,3 +20,5 @@
                                          " --group-directories-first"))))
 
 (provide 'init-dired)
+
+;;; init-dired.el ends here
diff --git a/lisp/init-editing.el b/lisp/init-editing.el
index 447f256..2fc8222 100644
--- a/lisp/init-editing.el
+++ b/lisp/init-editing.el
@@ -1,3 +1,7 @@
+;;; init-editing.el --- configure editing bindings and behaviour
+;;; Commentary:
+;;; Code:
+
 ;; use zap-up-to-char instead of zap-to-char
 (use-package misc
   :bind ("M-z" . zap-up-to-char))
@@ -30,3 +34,5 @@
 (setq yank-excluded-properties t)
 
 (provide 'init-editing)
+
+;;; init-editing.el ends here
diff --git a/lisp/init-eglot.el b/lisp/init-eglot.el
index fad9f25..1ee07ef 100644
--- a/lisp/init-eglot.el
+++ b/lisp/init-eglot.el
@@ -1,4 +1,9 @@
+;;; init-eglot.el --- configure lsp integration
+;;; Commentary:
+;;; Code:
+
 (defun mpolden/format-before-save ()
+  "Format buffer using `eglot-format' unless explicitly inhibited in current mode."
   (unless (member major-mode (bound-and-true-p mpolden/inhibit-format-before-save))
     (eglot-format)))
 
@@ -33,3 +38,5 @@
                                            :hoverProvider)))
 
 (provide 'init-eglot)
+
+;;; init-eglot.el ends here
diff --git a/lisp/init-flymake.el b/lisp/init-flymake.el
index c07ed8d..0edc521 100644
--- a/lisp/init-flymake.el
+++ b/lisp/init-flymake.el
@@ -1,6 +1,12 @@
+;;; init-flymake.el --- configure flymake
+;;; Commentary:
+;;; Code:
+
 (use-package flymake
   :bind (:map flymake-mode-map
               ;; C-d shows a list of all errors
               ("C-c d" . flymake-show-diagnostics-buffer)))
 
 (provide 'init-flymake)
+
+;;; init-flymake.el ends here
diff --git a/lisp/init-flyspell.el b/lisp/init-flyspell.el
index 2ac7a3e..ce64dd2 100644
--- a/lisp/init-flyspell.el
+++ b/lisp/init-flyspell.el
@@ -1,3 +1,7 @@
+;;; init-flyspell.el --- configure flyspell
+;;; Commentary:
+;;; Code:
+
 (use-package flyspell
   ;; load flyspell automatically for these modes
   :hook ((git-commit-mode . flyspell-mode)
@@ -14,3 +18,5 @@
     (setq ispell-program-name "hunspell")))
 
 (provide 'init-flyspell)
+
+;;; init-flyspell.el ends here
diff --git a/lisp/init-git.el b/lisp/init-git.el
index 9a39bcd..93a8de8 100644
--- a/lisp/init-git.el
+++ b/lisp/init-git.el
@@ -1,3 +1,7 @@
+;;; init-git.el --- configure git and forge integration
+;;; Commentary:
+;;; Code:
+
 (use-package git-commit
   :ensure t
   :after markdown-mode
@@ -7,7 +11,8 @@
   (setq git-commit-major-mode 'gfm-mode))
 
 (defun mpolden/magit-visit-file-other-window (&optional noselect)
-  "Visit current file in another window."
+  "Visit current file in another window.
+If NOSELECT is non-nil, do not select the window."
   (interactive)
   (let ((current-window (selected-window)))
     (call-interactively 'magit-diff-visit-file-other-window)
@@ -63,3 +68,5 @@
   (setq smerge-command-prefix (kbd "C-c x")))
 
 (provide 'init-git)
+
+;;; init-git.el ends here
diff --git a/lisp/init-go.el b/lisp/init-go.el
index ae22c9b..450bd20 100644
--- a/lisp/init-go.el
+++ b/lisp/init-go.el
@@ -1,5 +1,9 @@
+;;; init-go.el --- configure go language support
+;;; Commentary:
+;;; Code:
+
 (defun mpolden/go-mode-buffer-local-variables ()
-  ;; adjust fill-column
+  "Set buffer-local variables for `go-mode'."
   (setq-local fill-column 120))
 
 (use-package go-mode
@@ -7,3 +11,5 @@
   :hook (go-mode . mpolden/go-mode-buffer-local-variables))
 
 (provide 'init-go)
+
+;;; init-go.el ends here
diff --git a/lisp/init-grep.el b/lisp/init-grep.el
index c362ec4..92af755 100644
--- a/lisp/init-grep.el
+++ b/lisp/init-grep.el
@@ -1,18 +1,23 @@
-(defun mpolden/grep-visit-buffer-other-window (&optional event noselect)
-  "Visit grep result in another window."
+;;; init-grep.el --- configure grep
+;;; Commentary:
+;;; Code:
+
+(defun mpolden/grep-visit-buffer-other-window (&optional result noselect)
+  "Visit grep RESULT in another window.
+If NOSELECT is non-nil, do not select the window."
   (interactive)
   (let ((current-window (selected-window)))
-    (compile-goto-error event)
+    (compile-goto-error result)
     (when noselect
       (select-window current-window))))
 
-(defun mpolden/grep-visit-buffer-other-window-noselect (&optional event)
-  "Visit grep result in another window, but don't select it."
+(defun mpolden/grep-visit-buffer-other-window-noselect (&optional result)
+  "Visit grep RESULT another window, but don't select it."
   (interactive)
   (mpolden/grep-visit-buffer-other-window event t))
 
 (defun mpolden/grep-mode-buffer-local-variables ()
-  ;; wrap lines
+  "Set buffer-local variables for `grep-mode'."
   (setq-local truncate-lines nil))
 
 (use-package grep
@@ -29,3 +34,5 @@
               ("p" . compilation-previous-error)))
 
 (provide 'init-grep)
+
+;;; init-grep.el ends here
diff --git a/lisp/init-ibuffer.el b/lisp/init-ibuffer.el
index abba8a1..0605fb1 100644
--- a/lisp/init-ibuffer.el
+++ b/lisp/init-ibuffer.el
@@ -1,3 +1,7 @@
+;;; init-ibuffer.el --- configure ibuffer and vc integration
+;;; Commentary:
+;;; Code:
+
 (use-package ibuffer
   :init
   ;; disable confirmation for killing unmodified buffers
@@ -32,3 +36,5 @@
          ("g" . ibuffer-vc-set-filter-groups-by-vc-root)))
 
 (provide 'init-ibuffer)
+
+;;; init-ibuffer.el ends here
diff --git a/lisp/init-imenu.el b/lisp/init-imenu.el
index f66bb77..0870c4f 100644
--- a/lisp/init-imenu.el
+++ b/lisp/init-imenu.el
@@ -1,3 +1,7 @@
+;;; init-imenu.el --- configure imenu
+;;; Commentary:
+;;; Code:
+
 (use-package imenu
   :init
   ;; make imenu automatically rescan buffers
@@ -7,3 +11,5 @@
   :bind ("C-c i" . imenu))
 
 (provide 'init-imenu)
+
+;;; init-imenu.el ends here
diff --git a/lisp/init-ivy.el b/lisp/init-ivy.el
index bad546b..2a7692f 100644
--- a/lisp/init-ivy.el
+++ b/lisp/init-ivy.el
@@ -1,3 +1,7 @@
+;;; init-ivy.el --- configure ivy
+;;; Commentary:
+;;; Code:
+
 ;; ivy uses flx sorting if it's installed
 (use-package flx
   :ensure t)
@@ -14,3 +18,5 @@
   (ivy-mode 1))
 
 (provide 'init-ivy)
+
+;;; init-ivy.el ends here
diff --git a/lisp/init-javascript.el b/lisp/init-javascript.el
index 145d5f9..f0f8228 100644
--- a/lisp/init-javascript.el
+++ b/lisp/init-javascript.el
@@ -1,3 +1,7 @@
+;;; init-javascript.el --- configure javascript language support
+;;; Commentary:
+;;; Code:
+
 (use-package js
   :init
   ;; set indent level to 2
@@ -12,3 +16,5 @@
               ("C-c f" . json-pretty-print-buffer)))
 
 (provide 'init-javascript)
+
+;;; init-javascript.el ends here
diff --git a/lisp/init-lisp.el b/lisp/init-lisp.el
index 8c1eddb..0bb2233 100644
--- a/lisp/init-lisp.el
+++ b/lisp/init-lisp.el
@@ -1,3 +1,7 @@
+;;; init-lisp.el --- configure lisp language support
+;;; Commentary:
+;;; Code:
+
 (use-package paredit
   :ensure t
   :config
@@ -10,3 +14,5 @@
   :diminish)
 
 (provide 'init-lisp)
+
+;;; init-lisp.el ends here
diff --git a/lisp/init-mac.el b/lisp/init-mac.el
index 8231f79..a611a7f 100644
--- a/lisp/init-mac.el
+++ b/lisp/init-mac.el
@@ -1,3 +1,7 @@
+;;; init-mac.el --- configuration specific to macos
+;;; Commentary:
+;;; Code:
+
 ;; use jetbrains mono font if available
 ;; https://www.jetbrains.com/lp/mono/
 (let ((font-family "JetBrains Mono"))
@@ -43,3 +47,5 @@
   (setq insert-directory-program "gls"))
 
 (provide 'init-mac)
+
+;;; init-mac.el ends here
diff --git a/lisp/init-markdown.el b/lisp/init-markdown.el
index c99add9..58645d1 100644
--- a/lisp/init-markdown.el
+++ b/lisp/init-markdown.el
@@ -1,3 +1,7 @@
+;;; init-markdown.el --- configure markdown language support
+;;; Commentary:
+;;; Code:
+
 (use-package markdown-mode
   :ensure t
   :commands gfm-mode
@@ -9,3 +13,5 @@
    ("ISSUE_EDITMSG" . gfm-mode)))
 
 (provide 'init-markdown)
+
+;;; init-markdown.el ends here
diff --git a/lisp/init-org.el b/lisp/init-org.el
index 9bbd73e..9d0e830 100644
--- a/lisp/init-org.el
+++ b/lisp/init-org.el
@@ -1,3 +1,7 @@
+;;; init-org.el --- configure org
+;;; Commentary:
+;;; Code:
+
 (use-package org
   :bind (("C-c c" . org-capture)
          ("C-c l" . org-store-link)
@@ -90,3 +94,5 @@
   :after org)
 
 (provide 'init-org)
+
+;;; init-org.el ends here
diff --git a/lisp/init-package.el b/lisp/init-package.el
index bdfa19e..ae97c24 100644
--- a/lisp/init-package.el
+++ b/lisp/init-package.el
@@ -1,3 +1,7 @@
+;;; init-package.el --- configure package management
+;;; Commentary:
+;;; Code:
+
 ;; add melpa repo
 (require 'package)
 (add-to-list 'package-archives
@@ -29,6 +33,7 @@ re-downloaded in order to locate PACKAGE."
 (define-obsolete-variable-alias 'inhibited-packages 'mpolden/inhibited-packages)
 
 (defun mpolden/maybe-require (package)
+  "Load PACKAGE if it's not inhibited."
   (unless (member package (bound-and-true-p mpolden/inhibited-packages))
     (require package)))
 
@@ -42,3 +47,5 @@ re-downloaded in order to locate PACKAGE."
 (require 'bind-key)
 
 (provide 'init-package)
+
+;;; init-package.el ends here
diff --git a/lisp/init-project.el b/lisp/init-project.el
index b69e6a9..fd84534 100644
--- a/lisp/init-project.el
+++ b/lisp/init-project.el
@@ -1,4 +1,9 @@
+;;; init-project.el --- configure project integration
+;;; Commentary:
+;;; Code:
+
 (defun mpolden/project-git-grep ()
+  "Run git grep interactively in the current project."
   (interactive)
   (let ((search-regexp (grep-read-regexp))
         (dir (project-root (project-current t))))
@@ -23,3 +28,5 @@
          ("C-c m" . project-compile)))
 
 (provide 'init-project)
+
+;;; init-project.el ends here
diff --git a/lisp/init-python.el b/lisp/init-python.el
index b760a34..4ddf92b 100644
--- a/lisp/init-python.el
+++ b/lisp/init-python.el
@@ -1,4 +1,9 @@
+;;; init-python.el --- configure python language support
+;;; Commentary:
+;;; Code:
+
 (defun mpolden/python-mode-buffer-local-variables ()
+  "Set buffer-local variables for `python-mode'."
   ;; highlight lines longer than 88 characters
   (setq-local fill-column 88)
   ;; use flat index in imenu
@@ -18,3 +23,5 @@
     (setq python-shell-interpreter "python3")))
 
 (provide 'init-python)
+
+;;; init-python.el ends here
diff --git a/lisp/init-recentf.el b/lisp/init-recentf.el
index 25e7481..6f0ba41 100644
--- a/lisp/init-recentf.el
+++ b/lisp/init-recentf.el
@@ -1,3 +1,7 @@
+;;; init-recentf.el --- configure recentf
+;;; Commentary:
+;;; Code:
+
 (use-package recentf
   :init
   ;; set number of entries to save
@@ -9,3 +13,5 @@
   (recentf-mode 1))
 
 (provide 'init-recentf)
+
+;;; init-recentf.el ends here
diff --git a/lisp/init-restclient.el b/lisp/init-restclient.el
index 4740764..070153d 100644
--- a/lisp/init-restclient.el
+++ b/lisp/init-restclient.el
@@ -1,3 +1,7 @@
+;;; init-restclient.el --- configure restclient
+;;; Commentary:
+;;; Code:
+
 (use-package restclient
   :ensure t
   :init
@@ -9,3 +13,5 @@
   :mode (("\\.http\\'" . restclient-mode)))
 
 (provide 'init-restclient)
+
+;;; init-restclient.el ends here
diff --git a/lisp/init-rust.el b/lisp/init-rust.el
index 4b755db..21f02c9 100644
--- a/lisp/init-rust.el
+++ b/lisp/init-rust.el
@@ -1,3 +1,7 @@
+;;; init-rust.el --- configure rust language support
+;;; Commentary:
+;;; Code:
+
 (use-package rust-mode
   :ensure t
   :bind (:map rust-mode-map
@@ -6,3 +10,5 @@
               ("C-c R" . rust-run)))
 
 (provide 'init-rust)
+
+;;; init-rust.el ends here
diff --git a/lisp/init-sane-defaults.el b/lisp/init-sane-defaults.el
index 3fbe741..bd19c5f 100644
--- a/lisp/init-sane-defaults.el
+++ b/lisp/init-sane-defaults.el
@@ -1,3 +1,7 @@
+;;; init-sane-defaults.el --- configure sane defaults
+;;; Commentary:
+;;; Code:
+
 ;; use soft tabs
 (setq-default indent-tabs-mode nil)
 
@@ -88,3 +92,5 @@
 (setq calendar-week-start-day 1)
 
 (provide 'init-sane-defaults)
+
+;;; init-sane-defaults.el ends here
diff --git a/lisp/init-server.el b/lisp/init-server.el
index f6e510c..6ef2451 100644
--- a/lisp/init-server.el
+++ b/lisp/init-server.el
@@ -1,7 +1,12 @@
-;; start server for emacsclient
+;;; init-server.el --- configure server for emacsclient
+;;; Commentary:
+;;; Code:
+
 (use-package server
   :config
   (unless (server-running-p)
     (server-start)))
 
 (provide 'init-server)
+
+;;; init-server.el ends here
diff --git a/lisp/init-theme.el b/lisp/init-theme.el
index 6f9a214..42567ca 100644
--- a/lisp/init-theme.el
+++ b/lisp/init-theme.el
@@ -1,4 +1,7 @@
-;; set theme
+;;; init-theme.el --- configure theme
+;;; Commentary:
+;;; Code:
+
 (use-package doom-themes
   :ensure t
   :if (display-graphic-p)
@@ -11,3 +14,5 @@
                                 (ns-transparent-title-bar . t)))))
 
 (provide 'init-theme)
+
+;;; init-theme.el ends here
diff --git a/lisp/init-tramp.el b/lisp/init-tramp.el
index 9aa268b..9c56f1f 100644
--- a/lisp/init-tramp.el
+++ b/lisp/init-tramp.el
@@ -1,3 +1,7 @@
+;;; init-tramp.el --- configure tramp
+;;; Commentary:
+;;; Code:
+
 (defun mpolden/sudo-prefix-p (prefix)
   "Return non-nil if PREFIX is a sudo prefix."
   (member prefix '("/sudo" "/sudo:")))
@@ -30,6 +34,7 @@ With a prefix ARG prompt edit currently visited file using sudo."
     (find-file (mpolden/sudo-file-name (read-file-name "Find file with sudo: ")))))
 
 (defun mpolden/sudo-current-file ()
+  "Open current file with sudo."
   (interactive)
   (mpolden/sudo-find-file t))
 
@@ -45,3 +50,5 @@ With a prefix ARG prompt edit currently visited file using sudo."
                '((regexp-quote (system-name)) nil nil)))
 
 (provide 'init-tramp)
+
+;;; init-tramp.el ends here
diff --git a/lisp/init-writegood.el b/lisp/init-writegood.el
index 99e6bdc..75f3cda 100644
--- a/lisp/init-writegood.el
+++ b/lisp/init-writegood.el
@@ -1,3 +1,7 @@
+;;; init-writegood.el --- configure weasel word detection
+;;; Commentary:
+;;; Code:
+
 (use-package writegood-mode
   :ensure t
   :hook
@@ -5,3 +9,5 @@
   (flyspell-mode . writegood-mode))
 
 (provide 'init-writegood)
+
+;;; init-writegood.el ends here
diff --git a/lisp/init-yaml.el b/lisp/init-yaml.el
index 4e87a9a..b53ddfb 100644
--- a/lisp/init-yaml.el
+++ b/lisp/init-yaml.el
@@ -1,4 +1,10 @@
+;;; init-yaml.el --- configure yaml language support
+;;; Commentary:
+;;; Code:
+
 (use-package yaml-mode
   :ensure t)
 
 (provide 'init-yaml)
+
+;;; init-yaml.el ends here