docs: normalize generated-file headers and prune obvious comments

The theme-studio and browser-choice generators now stamp their output with a header that names the authoritative source and says to regenerate rather than hand-edit. I regenerated both files to match. I also deleted six obvious "describe the next form" comments, replaced two stale placeholders in titlecase.el and an incomplete FIXME in org-checklist.el with real rationale, and condensed early-init's header and Commentary.

11 files changed, 21 insertions, 54 deletions

diff --git a/custom/org-checklist.el b/custom/org-checklist.el
index e7d9b4682..170f449e6 100644
--- a/custom/org-checklist.el
+++ b/custom/org-checklist.el
@@ -47,9 +47,8 @@
 ;;; Code:
 (require 'org)
 (defvar org-state)
-;; FIXME: This library requires
-;; https://git.savannah.gnu.org/cgit/a2ps.git/tree/contrib/emacs/a2ps-print.el file
-;; It is a part of a2ps distribution.
+;; Optional print support: a2ps-print.el ships with a2ps. Without it, checklist
+;; reset/export still works, but print commands that call a2ps-buffer are absent.
 (load "a2ps-print" 'no-error)
 (defvar a2ps-switches)
 (declare-function a2ps-buffer "a2ps-print" (argp))
diff --git a/custom/titlecase.el b/custom/titlecase.el
index 439478220..319befefd 100644
--- a/custom/titlecase.el
+++ b/custom/titlecase.el
@@ -175,7 +175,8 @@ for docs on BEGIN, END and STYLE."
                                            titlecase-skip-words-regexps
                                            "\\|")))
             (goto-char (match-end 0))
-            ;; TODO: Document what this does (it's late)
+            ;; If the skip regexp consumed the final word, exit before the main loop tries
+            ;; to advance past END.
             (when (>= (point) end)
               (throw :done 'skipped)))
            ;; Phrasal verbs!
@@ -210,16 +211,8 @@ for docs on BEGIN, END and STYLE."
            ((and (memq style titlecase-styles-capitalize-non-short-words)
                  (> (length this-word) titlecase-short-word-length))
             (capitalize-word 1))
-           ;; Sentence style just capitalizes the first word.  Since we can't be
-           ;; sure how the user has already capitalized anything, we just skip
-           ;; the current word.  HOWEVER, there are times when downcasing the
-           ;; rest of the sentence is warranted.  --- NOTE 2022-05-09: Now I'm
-           ;; thinking about it, does `sentence' style need to do anything
-           ;; whatsoever?  Maybe I just need to include a test toward the top of
-           ;; the enclosing function to make `titlecase-default-case-function'
-           ;; be `downcase-word' if `titlecase-downcase-sentences' is true... or
-           ;; something of that nature.  I might be over-engineering this, is
-           ;; what I'm saying.  Curious, isn't it?
+           ;; Sentence style either leaves later words unchanged or downcases them,
+           ;; depending on titlecase-downcase-sentences.
            ((eq style 'sentence)
             (funcall (if titlecase-downcase-sentences
                          #'downcase-word
diff --git a/early-init.el b/early-init.el
index 7ae814734..32f144cdb 100644
--- a/early-init.el
+++ b/early-init.el
@@ -1,36 +1,14 @@
-;;; early-init.el ---  -*- lexical-binding: t; coding: utf-8; no-byte-compile: t; -*-
+;;; early-init.el --- Startup bootstrap before init.el -*- lexical-binding: t; coding: utf-8; no-byte-compile: t; -*-
 
 ;;; Commentary:
-
-;; DEBUG FLAGS
-;; Debug flags are default on while this config is loading since errors should
-;; be loud and highly noticeable. They are restored to their default off once
-;; the config has completed.
-
-;; STARTUP PERFORMANCE
-;; Increasing garbage collection to a very high number decreases startup time.
-;; setting the file-name-handler and vc-handled-backends avoids some regexp
-;; slowness during startup. All original values are restored once Emacs is
-;; finished with startup.
-
-;; LOCAL REPOSITORIES
-;; This config doesn't work if the packages it relies on fail. Having local
-;; package repositories also allows for full config portability behind corporate
-;; firewalls and fast recovery from package issues no matter the network
-;; situation.
-
-;; The localrepo directory contains all the last known good packages for this
-;; config. The directory is added as a repository to the package archive list
-;; first, and given the highest priority number. This allows for a portable
-;; installation and reinstallation. This directory averages ~70 MB.
-
-;; Having a full local mirror of all elpa, melpa, and org repositories gives you
-;; more flexibility but at a higher storage cost. The script
-;; 'create-elpa-mirror.sh in user-emacs-directory/scripts directory will clone
-;; them all locally. As of Saturday, March 30, 2024 the directory containing all
-;; gnu, nongnu, melpa, melpa-stable, and org packages takes around 1.9 GB.
-;; For more information on the localrepo and elpa mirrors, read the commentary
-;; in local-repository.el.
+;;
+;; Early startup policy: make init errors loud, speed package/bootstrap work,
+;; configure package archives, and suppress expensive UI defaults before the
+;; first frame appears.
+;;
+;; Package archives prefer the checked-in localrepo, then local ELPA mirrors,
+;; then online archives. Startup-only GC and file-name-handler changes are
+;; paired with later session owners such as gcmh.
 
 ;;; Code:
 
diff --git a/modules/browser-config.el b/modules/browser-config.el
index d596b9e9d..564e7a275 100644
--- a/modules/browser-config.el
+++ b/modules/browser-config.el
@@ -76,7 +76,10 @@ Includes built-in Emacs browsers (those with nil executable)."
 (defun cj/save-browser-choice (browser-plist)
   "Save BROWSER-PLIST to the persistence file."
   (with-temp-file cj/browser-choice-file
-    (insert ";;; Browser choice - Auto-generated\n")
+    (insert ";;; browser-choice.el --- Generated browser selection -*- lexical-binding: t; -*-\n")
+    (insert ";;\n")
+    (insert ";; Generated by browser-config.el. Do not edit by hand; use\n")
+    (insert ";; `cj/choose-browser' to rewrite this file.\n")
     (insert (format "(setq cj/saved-browser-choice '%S)\n" browser-plist))))
 
 (defun cj/load-browser-choice ()
@@ -102,7 +105,6 @@ Returns: \\='success if applied successfully,
           (program-var (plist-get browser-plist :program-var)))
       (if (null browse-fn)
           'invalid-plist
-        ;; Set the main browse-url function
         (setq browse-url-browser-function browse-fn)
         ;; Set the specific browser program variable if it exists
         (when program-var
diff --git a/modules/calibredb-epub-config.el b/modules/calibredb-epub-config.el
index cd8101db1..10a78942c 100644
--- a/modules/calibredb-epub-config.el
+++ b/modules/calibredb-epub-config.el
@@ -178,7 +178,6 @@ Adjust it live with `cj/nov-widen-text' and `cj/nov-narrow-text'.")
   (if (and buffer-file-name
            (string-match-p "\\.epub\\'" buffer-file-name))
       (progn
-        ;; Load nov if not already loaded
         (unless (featurep 'nov)
           (require 'nov nil t))
         ;; Call nov-mode if available, otherwise fallback to default behavior
diff --git a/modules/font-config.el b/modules/font-config.el
index cb060b7be..7617ba01e 100644
--- a/modules/font-config.el
+++ b/modules/font-config.el
@@ -193,7 +193,6 @@ If FRAME is nil, uses the selected frame."
   (all-the-icons-nerd-fonts-prefer))
 
 ;; ----------------------------- Emoji Fonts Per OS ----------------------------
-;; Set emoji fonts in priority order (first found wins)
 
 (defun cj/setup-emoji-fontset (&optional _frame)
   "Set emoji fonts in priority order (first found wins).
diff --git a/modules/org-webclipper.el b/modules/org-webclipper.el
index a51350f51..40ceada76 100644
--- a/modules/org-webclipper.el
+++ b/modules/org-webclipper.el
@@ -52,7 +52,6 @@ See `cj/--webclip-url' for the binding contract.")
 (defun cj/webclipper-ensure-initialized ()
   "Ensure webclipper is initialized when first used."
   (unless cj/webclipper-initialized
-    ;; Load required packages now
     (require 'org-protocol)
     (require 'org-capture)
     (require 'org-web-tools)
diff --git a/modules/selection-framework.el b/modules/selection-framework.el
index 464654a20..7f7f9a475 100644
--- a/modules/selection-framework.el
+++ b/modules/selection-framework.el
@@ -128,7 +128,6 @@
   ;; Optionally tweak the register preview window.
   (advice-add #'register-preview :override #'consult-register-window)
 
-  ;; Configure other variables and modes
   (setq xref-show-xrefs-function #'consult-xref
         xref-show-definitions-function #'consult-xref)
 
diff --git a/modules/tramp-config.el b/modules/tramp-config.el
index e3b835f1f..f2bc8457c 100644
--- a/modules/tramp-config.el
+++ b/modules/tramp-config.el
@@ -57,7 +57,6 @@
   (setq tramp-auto-save-directory
 		(expand-file-name "tramp-auto-save" user-emacs-directory))
 
-  ;; Create directory if it doesn't exist
   (unless (file-exists-p tramp-auto-save-directory)
 	(make-directory tramp-auto-save-directory t))
 
diff --git a/scripts/theme-studio/build-theme.el b/scripts/theme-studio/build-theme.el
index 4432ef57c..e37214991 100644
--- a/scripts/theme-studio/build-theme.el
+++ b/scripts/theme-studio/build-theme.el
@@ -241,7 +241,7 @@ Empty-attr entries emit nothing (cleared faces drop out)."
    (format ";;; %s-theme.el --- Generated by theme-studio -*- lexical-binding: t -*-\n" name)
    "\n;;; Commentary:\n"
    (format ";; Generated from %s.json by scripts/theme-studio/build-theme.el.\n" name)
-   ";; Do not hand-edit; re-run the converter.\n"
+   ";; Treat the JSON as authoritative; regenerate instead of hand-editing this file.\n"
    "\n;;; Code:\n\n"
    (format "(deftheme %s\n  \"Generated by theme-studio.\")\n\n" name)
    (format "(custom-theme-set-faces\n '%s\n" name)
diff --git a/themes/WIP-theme.el b/themes/WIP-theme.el
index 93184fe40..843537d20 100644
--- a/themes/WIP-theme.el
+++ b/themes/WIP-theme.el
@@ -2,7 +2,7 @@
 
 ;;; Commentary:
 ;; Generated from WIP.json by scripts/theme-studio/build-theme.el.
-;; Do not hand-edit; re-run the converter.
+;; Treat the JSON as authoritative; regenerate instead of hand-editing this file.
 
 ;;; Code: