WIP: Addresssing checkdoc issues.

00.emacs-patches.el

@@ -1,9 +1,17 @@
-;;;; Patches for buggy/old emacs code  -*- lexical-binding: t; -*-
-;;;;
-;;;; This allows me to use one init file across multiple versions of Emacs.
-;;;;
-;;;; Currently tested against:
-;;;; * GNU Emacs 29.1
+;;; init/00.emacs-patches.el --- Patches for buggy/old emacs code  -*- lexical-binding: t; -*-
+
+;;; Commentary:
+;;
+;; This file serves two purposes:
+;;
+;; 1. It contains bugfixes for core Emacs functions.
+;; 2. It backports new Emacs functionality to earlier versions that
+;; are not yet available on Debian stable.
+;;
+;; Currently tested against:
+;; * GNU Emacs 29.1
+
+;;; Code:
 
 ;; Disallow navigating to the minibuffer
 (unless (eq (plist-get minibuffer-prompt-properties 'cursor-intangible) t)

00.required-libraries.el

@@ -1,10 +1,16 @@
-;;;; Misc utilities that I like to use throughout my init file.  -*- lexical-binding: t; -*-
+;;; init/00.required-libraries.el --- Misc utilities useful for init files  -*- lexical-binding: t; -*-
+
+;;; Code:
 (require 'cl-lib)
 (require 'package)
 
 ;;; A new and improved DEFMACRO. TODO(upstream)
 (defmacro defmacro+ (name args &rest body)
-  "Like `cl-defmacro', but also attempts to figure out the indenting."
+  "Like `cl-defmacro', but also attempts to figure out the indenting.
+
+NAME: Symbol to use as macro, as in `cl-defmacro'.
+ARGS: List of parameters to the macro, as in `cl-defmacro'.
+BODY: The body of the macro, as in `cl-defmacro'."
   (let ((body-index (cl-position-if (lambda (arg) (member arg '(&body &rest)))
                                     (remove '&optional args))))
     `(progn
@@ -28,14 +34,14 @@ This allows you to declaratively hook in minor modes on a major mode."
                          collect (list expr 1)
                        else if (listp expr)
                          collect expr
-                       else do (error "%s does not appear to name a minor mode." expr))))
+                       else do (error "%s does not appear to name a minor mode" expr))))
     `(hook-mode-attach ',hook (lambda () "Auto-generated by `hook-mode'"
                                 ,@body))))
 
 (defvar hook-mode-*hooks* (make-hash-table :test #'eq))
 (defun hook-mode-attach (hook function)
+  "Attach FUNCTION to HOOK."
   (when (gethash hook hook-mode-*hooks*)
     (remove-hook hook (gethash hook hook-mode-*hooks*)))
   (add-hook hook function)
   (setf (gethash hook hook-mode-*hooks*) function))
-

c.el

@@ -1,6 +1,6 @@
-;;;; C customizations.  -*- lexical-binding: t; -*-
-;;;;
-;;;; Also applied to other C-like languages (really anything that uses CC-mode)
+;;; init/c.el --- C based language customizations  -*- lexical-binding: t; -*-
+
+;;; Code:
 (hook-mode c-mode-common-hook
   visual-line-mode
   (c-set-offset 'case-label '+)
@@ -47,8 +47,12 @@
 ;; Make CC-Mode's defun finding include any function comments that
 ;; immediately preceede it.
 (defun my-c-beginning-of-defun (&optional arg)
-  "Move backward to the beginning of a defun, and any function
-comment right before it."
+  "Move backward to the beginning of a defun, including comments.
+
+Unlike `c-beginning-of-defun', this also includes the comment
+block in front of it.
+
+ARG: Number of defuns to move, as in `c-beginning-of-defun'."
   (ignore-errors
     (c-beginning-of-defun arg)
     (while (c-backward-single-comment))
@@ -57,7 +61,10 @@ comment right before it."
 ;; Make CScope use next-error functionality, so "C-x `" works correctly
 (defun cscope-next-error (n &optional reset)
   "Advance to the next error message and visit the file where the error was.
-This is the value of `next-error-function' in CScope buffers."
+This is the value of `next-error-function' in CScope buffers.
+
+N: Number of errors to move forward.
+RESET: If non-nil, start from the beginning."
   (let ((buffer (get-buffer cscope-output-buffer-name)))
     (when reset
       (with-current-buffer buffer

compilation.el

@@ -1,4 +1,6 @@
-;;;; Compilation mode customizations  -*- lexical-binding: t; -*-
+;;; init/compilation.el --- Compilation mode customizations  -*- lexical-binding: t; -*-
+
+;;; Code:
 (hook-mode compilation-mode-hook
   next-error-follow-minor-mode)
 (hook-mode occur-mode-hook

custom.el

@@ -1,4 +1,6 @@
-;; -*- lexical-binding: t; -*-
+;;; init/custom.el --- Location for changes from Custom. -*- lexical-binding: t; -*-
+
+;;; Code:
 (put 'downcase-region 'disabled nil)
 (put 'upcase-region 'disabled nil)
 (put 'narrow-to-region 'disabled nil)

diff.el

@@ -1,17 +1,36 @@
-;;;; Diff mode customizations  -*- lexical-binding: t; -*-
+;;; init/diff.el --- Diff mode customizations  -*- lexical-binding: t; -*-
+
+;;; Code:
 (defun hexl-find-file-noselect (file)
-  "Find a file and put it into hexl-mode."
+  "Find a file and put it into `hexl-mode'.
+
+FILE: Path to a file to find."
     (let ((buffer (find-file-noselect file nil t)))
       (with-current-buffer buffer
         (hexl-mode 1))
       buffer))
 
 (defun ediff-binary-files (file1 file2)
+  "Diff two binary files with `ediff'.
+
+The diff will be done on the binary contents with both buffers in
+`hexl-mode'.
+
+FILE1: Path to the first file.
+FILE2: Path to the second file."
   (interactive (list (read-file-name "File A to compare: ")
                      (read-file-name "File B to compare: ")))
   (apply #'ediff-buffers (mapcar #'hexl-find-file-noselect (list file1 file2))))
 
 (defun ediff-binary-files3 (file1 file2 file3)
+  "Diff three binary files with `ediff3'.
+
+The diff will be done on the binary contents with all buffers in
+`hexl-mode'.
+
+FILE1: Path to the first file.
+FILE2: Path to the second file.
+FILE3: Path to the third file."
   (interactive (list (read-file-name "File A to compare: ")
                      (read-file-name "File B to compare: ")
                      (read-file-name "File C to compare: ")))

dired.el

@@ -1,5 +1,6 @@
-;;;; Dired mode customizations. -*- lexical-binding: t; -*-
+;;; init/dired.el --- Dired mode customizations -*- lexical-binding: t; -*-
 
+;;; Code:
 (hook-mode dired-mode-hook
   (when window-system
     (dired-icon-mode 1))
@@ -31,5 +32,5 @@
   "Show VC status for the currently displayed directory."
   (interactive)
   (unless (eq major-mode 'dired-mode)
-    (error "`my-dired-vc-dir' only works in dired mode."))
+    (error "`my-dired-vc-dir' only works in Dired mode"))
   (vc-dir (dired-current-directory)))

early-init.el

@@ -1,8 +1,14 @@
-;;;; Visual changes that affect the initial frame.  -*- lexical-binding: t; -*-
+;;; init/early-init.el --- Visual changes that affect the initial frame  -*- lexical-binding: t; -*-
 
+;;; Commentary:
+;;
 ;; This file should only be loaded during the early init and not
-;; during regular init. `early-init-file' is set after the early init
-;; process, which serves as a clear flag.
+;; during regular init.  This is only for fundamental visual changes
+;; that would otherwise cause Emacs to flicker during startup.
+
+;;; Code:
+;; `early-init-file' is set after the early init process, which serves
+;; as a clear flag.
 (unless early-init-file
   (setf modus-themes-headings
         '((1 . (variable-pitch (height 1.5)))

elisp.el

@@ -1,4 +1,6 @@
-;;;; Emacs Lisp customizations  -*- lexical-binding: t; -*-
+;;; init/elisp.el --- Emacs Lisp customizations  -*- lexical-binding: t; -*-
+
+;;; Code:
 (hook-mode emacs-lisp-mode-hook
   eldoc-mode
   (font-lock-add-keywords nil '(("^\\s *;;;.*\n?" (0 'section-comment-face t))

emacs.el

@@ -1,6 +1,6 @@
-;;;; Global Emacs customizations.  -*- lexical-binding: t; -*-
-;;;;
-;;;; Put stuff here if you have nowhere else to put them
+;;; init/emacs.el --- Global Emacs customizations  -*- lexical-binding: t; -*-
+
+;;; Code:
 (unless (fboundp 'bar-cursor-mode)
   ;; If this triggers, make sure to install the `bar-cursor' package
   ;; from melpa unstable.
@@ -144,11 +144,11 @@
 ;;; stand out a bit more.
 (defface section-comment-face
   '((t (:height 1.3 :inherit (font-lock-comment-face variable-pitch))))
-  "Face for section level comments"
+  "Face for section level comments."
   :group 'local)
 (defface file-comment-face
   '((t (:height 1.5 :weight bold :inherit (font-lock-comment-face variable-pitch))))
-  "Face for file level comments"
+  "Face for file level comments."
   :group 'local)
 
 ;; Also make same adjustments for markdown.
@@ -181,7 +181,7 @@
                          (interactive)
                          (if (> (length (frame-list)) 1)
                              (delete-frame)
-                           (when (y-or-n-p "Last frame, kill emacs? ")
+                           (when (y-or-n-p "Last frame, kill Emacs? ")
                              (call-interactively #'save-buffers-kill-emacs)))))))
 
 ;; Account for differences in Win32 keycodes
@@ -223,7 +223,9 @@
       (beginning-of-line))))
 
 (defun end-of-line-dwim (&optional n)
-  "Movie point to the last non-whitespace character or the end of line."
+  "Movie point to the last non-whitespace character or the end of line.
+
+N: Number of lines to go forward."
   (interactive "^p")
 
   (let ((point (point)))
@@ -237,7 +239,10 @@
 
 ;;; Recursive edits TODO(package)
 (defun push-or-pop-excursion (pop?)
-  "Pushes or pops an excursion, depending on the prefix arg."
+  "Pushes or pops an excursion, depending on the prefix arg.
+
+POP?: If nil (the default), then push an excursion.  Otherwise,
+pop an excursion."
   (interactive (list current-prefix-arg))
 
   (if (not pop?)
@@ -248,6 +253,12 @@
 
 ;;; Sibling file navigation TODO(upstream)
 (defun my-find-sibling-file-other-window (file)
+  "Variant of `find-sibling-file', that opens in another window.
+
+When called interactively, find the sibling of the current
+buffer's file.
+
+FILE: File to find the sibling file of."
   (interactive (progn
                  (unless buffer-file-name
                    (user-error "Not visiting a file"))
@@ -258,6 +269,12 @@
     (let ((this-command t))
       (run-hooks 'post-command-hook))))
 (defun my-find-sibling-file-other-frame (file)
+  "Variant of `find-sibling-file', that opens in another frame.
+
+When called interactively, find the sibling of the current
+buffer's file.
+
+FILE: File to find the sibling file of."
   (interactive (progn
                  (unless buffer-file-name
                    (user-error "Not visiting a file"))
@@ -285,7 +302,7 @@
 (defun indent-dwim (arg)
   "Try to do what a human would mean when indenting.
 
-The prefix argument, if given, indents to that column"
+The prefix argument ARG, if given, indents to that column."
   (interactive (list current-prefix-arg))
 
   (cond (mark-active

hexl.el

@@ -1,4 +1,6 @@
-;;;; Hexl (hex editor) customizations.  -*- lexical-binding: t; -*-
+;;; init/hexl.el --- Hexl (hex editor) customizations  -*- lexical-binding: t; -*-
+
+;;; Code:
 (with-eval-after-load 'hexl
   (hook-mode hexl-mode-hook
     (hexl-follow-line)
@@ -28,7 +30,11 @@
 
 ;; TODO(upstream)
 (defun hexl-insert-nybble (ch arg)
-  "Insert nybble for character ch arg times."
+  "Insert nybble for character CH, ARG times.
+
+CH: Character for a nybble to insert.  This should be a
+    hexadecimal digit, ?0 - ?9 or ?A -?F.
+ARG: Number of times to insert the above character."
   (when (not (or (<= ?0 ch ?9)
                  (<= ?a ch ?f)
                  (<= ?A ch ?F)))
@@ -47,7 +53,9 @@
       (goto-char (+ hex-position index 1)))))
 
 (defun hexl-my-self-insert-command (arg)
-  "Replacement for `hexl-self-insert-command'."
+  "Replacement for `hexl-self-insert-command'.
+
+ARG: Number of times to insert the character."
   (interactive "p")
   (if (< (current-column) (hexl-ascii-start-column))
       (hexl-insert-nybble last-command-event arg)
@@ -65,50 +73,73 @@
                               1 0)))))
 
 (defun hexl-my-ascii-position (addr)
+  "Return the buffer position in the ascii column.
+
+ADDR: Address to get the position for, as returned from
+`hexl-current-address'."
   (+ (* (/ addr 16) (hexl-line-displen))
      (hexl-ascii-start-column)
      (point-min)
      (% addr 16)))
 
 (defun hexl-my-movement (f arg)
+  "Execute movement function F, staying in ASCII or bytes column.
+
+F: Function to execute.
+ARG: Argument to pass to F, as (F ARG)."
   (let ((at-ascii-position (>= (current-column) (hexl-ascii-start-column))))
     (funcall f arg)
     (when at-ascii-position
       (goto-char (hexl-my-ascii-position (hexl-current-address t))))))
 
 (defun hexl-my-movement0 (f)
+  "Execute movement function F, staying in ASCII or bytes column.
+
+F: Function to execute."
   (let ((at-ascii-position (>= (current-column) (hexl-ascii-start-column))))
     (funcall f)
     (when at-ascii-position
       (goto-char (hexl-my-ascii-position (hexl-current-address t))))))
 
 (defun hexl-my-backward-char (arg)
-  "Replacement for `hexl-backward-char'."
+  "Replacement for `hexl-backward-char'.
+
+ARG: Number of characters to move."
   (interactive "p")
   (hexl-my-forward-char (- arg)))
 
 (defun hexl-my-forward-char (arg)
-  "Replacement for `hexl-forward-char'."
+  "Replacement for `hexl-forward-char'.
+
+ARG: Number of characters to move."
   (interactive "p")
   (hexl-my-movement 'hexl-my-forward-char-internal arg))
 
 (defun hexl-my-previous-line (arg)
-  "Replacement for `hexl-previous-line'."
+  "Replacement for `hexl-previous-line'.
+
+ARG: Number of lines to move."
   (interactive "p")
   (hexl-my-movement 'hexl-previous-line arg))
 
 (defun hexl-my-next-line (arg)
-  "Replacement for `hexl-next-line'."
+  "Replacement for `hexl-next-line'.
+
+ARG: Number of lines to move."
   (interactive "p")
   (hexl-my-movement 'hexl-next-line arg))
 
 (defun hexl-my-beginning-of-buffer (arg)
-  "Replacement for `hexl-beginning-of-buffer'."
+  "Replacement for `hexl-beginning-of-buffer'.
+
+ARG: Passed to `hexl-beginning-of-buffer'."
   (interactive "p")
   (hexl-my-movement 'hexl-beginning-of-buffer arg))
 
 (defun hexl-my-end-of-buffer (arg)
-  "Replcaement for `hexl-end-of-buffer'."
+  "Replcaement for `hexl-end-of-buffer'.
+
+ARG: Passed to `hexl-end-of-buffer'."
   (interactive "p")
   (hexl-my-movement 'hexl-end-of-buffer arg))