summary history branches tags files
commit:9e2d34df492a4193b7321fde312e9d110f768fc4
author:Trevor Bentley
committer:Trevor Bentley
date:Thu Dec 10 23:32:26 2020 +0100
parents:7fee9060993c78162627c51280b8c2038a786ca8
checkdoc is VERY picky
diff --git a/snitch-backtrace.el b/snitch-backtrace.el
line changes: +53/-26
index 3059222..0906428
--- a/snitch-backtrace.el
+++ b/snitch-backtrace.el
@@ -1,4 +1,4 @@
-;;; snitch-backtrace.el                    -*- lexical-binding: t; -*-
+;;; snitch-backtrace.el -- part of snitch  -*- lexical-binding: t; -*-
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 ;;
 ;; See snitch.el for full details.
@@ -58,24 +58,33 @@
   "Cache a list of the Emacs site-lisp root directories.")
 
 (defvar snitch--function-to-file-cache nil
-  "Hash table cache of function names to the file the functions
-is defined in.")
+  "Cache of function-to-file mappings.
+
+Hash table cache of function names to the file the functions are
+defined in.")
 
 (defvar snitch--package-dirs-cache '()
-  "Hash table cache mapping elisp directories to active
-packages.")
+  "Cache of elisp package directories.
+
+Hash table cache mapping elisp directories to active packages.")
 
 
 (defun snitch--fn-hash-cmp (a b)
-  "Hash comparison function for function/package hash table,
+  "Hash comparison for function/package cache.
+
+Hash comparison function for function/package hash table,
 since functions can be either function objects or strings and
-require different comparisons."
+require different comparisons.
+
+Return t if A equals B."
   (if (and (functionp a) (functionp b))
       (eq a b)
     (equal a b)))
 
 (defun snitch--find-function-file (fn)
-  "Look up the file a function is defined in, caching it in a
+  "Find file owning function FN.
+
+Look up the file a function is defined in, caching it in a
 hash table for quicker subsequent accesses."
   (unless snitch--function-to-file-cache
     (define-hash-table-test 'snitch-fn-hash-cmp
@@ -93,8 +102,10 @@ hash table for quicker subsequent accesses."
             nil))))))
 
 (defun snitch--site-lisp-dirs ()
-  "Find all directories in elisp load path that are not in the
-user dir."
+  "Find site-lisp directories.
+
+Find all directories in elisp load path that are not in the user
+dir."
   (if (not snitch--site-lisp-dir-cache)
       (let* ((user-dir (expand-file-name user-emacs-directory))
              (pkg-dir (expand-file-name package-user-dir))
@@ -111,7 +122,9 @@ user dir."
     snitch--site-lisp-dir-cache))
 
 (defun snitch--site-lisp-roots ()
-  "Find the 'root' directories, hopefully a list of
+  "Find the root site-lisp directories.
+
+Find the 'root' directories, hopefully a list of
 system-wide/non-user base directories containing elisp files."
   (if (not snitch--site-lisp-root-cache)
       (let ((dirs
@@ -124,7 +137,9 @@ system-wide/non-user base directories containing elisp files."
     snitch--site-lisp-root-cache))
 
 (defun snitch--dir-in-site-lisp (dir)
-  "Check if directory DIR is a subdirectory of one of the
+  "Check if DIR is in a site-lisp directory.
+
+Check if directory DIR is a subdirectory of one of the
 system-wide elisp directories found by
 `snitch--site-lisp-roots'."
   (not (null (cl-loop for site-dir in (snitch--site-lisp-roots)
@@ -132,8 +147,10 @@ system-wide elisp directories found by
                       collect site-dir))))
 
 (defun snitch--fill-package-dirs-cache ()
-  "Cache package directories in a hash table for faster
-subsequent accesses."
+  "Fill package directory cache.
+
+Cache package directories in a hash table for faster subsequent
+accesses."
   (setq snitch--package-dirs-cache
         (make-hash-table :test 'equal :size (length (package--alist))))
   (cl-loop for (pkgname . pkgdesc) in (package--alist)
@@ -144,8 +161,10 @@ subsequent accesses."
   (hash-table-count snitch--package-dirs-cache))
 
 (defun snitch--package-from-dir (dir)
-  "Given a directory DIR, returns a package that owns the files
-in that directory."
+  "Find package that owns directory DIR.
+
+Given a directory DIR, returns a package that owns the files in
+that directory."
   (when (null snitch--package-dirs-cache)
     (snitch--fill-package-dirs-cache))
   (gethash (file-name-as-directory dir) snitch--package-dirs-cache))
@@ -171,9 +190,11 @@ one of the following special values:
           'user)))))
 
 (defun snitch--maybe-add-timer-backtrace (bt timer)
-  "If the given backtrace BT terminates in the timer execution
+  "Try to add a saved timer backtrace to current backtrace.
+
+If the given backtrace BT terminates in the timer execution
 handler, check if snitch has cached the backtrace for the
-executing timer and append that backtrace to BT."
+executing timer, TIMER, and append that backtrace to BT."
   (let ((last-fn (nth 0 (car bt)))
         (reverse-bt (nreverse bt)))
     (if (eq last-fn #'timer-event-handler)
@@ -184,10 +205,12 @@ executing timer and append that backtrace to BT."
       reverse-bt)))
 
 (defun snitch--backtrace (&optional follow-timer)
-  "Return a full list of backtrace entries (the full function
-call stack) where each entry is a list containing (FUNCTION PATH
-PACKAGE).  Entries related to the snitch callstack are
-filtered out.
+  "Return a backtrace usable by snitch.
+
+Return a full list of backtrace entries (the full function call
+stack) where each entry is a list containing (FUNCTION PATH
+PACKAGE).  Entries related to the snitch callstack are filtered
+out.
 
 FUNCTION is a function symbol if available, or one of the special
 symbols ‘lambda’, ‘macro’, or ‘compiled-function’ otherwise.
@@ -260,7 +283,9 @@ concatenated together."
       (nreverse stack))))
 
 (defun snitch--package-type-more-important (a b)
-  "Return t if package type of 'a' is more important than the
+  "Determine if A is a more important package than B.
+
+Return t if package type of 'a' is more important than the
 package type of b, where:
 
 - nil > nil
@@ -276,7 +301,7 @@ started the chain.
 
 On the other hand, for packages, we really want to focus on the
 very last function that was responsible for triggering the rest
-of the emacs internal activity."
+of the Emacs internal activity."
   (cond
    ;; nil only greater than nil
    ((null a) (member b (list nil)))
@@ -294,8 +319,10 @@ of the emacs internal activity."
 
 
 (defun snitch--responsible-caller (backtrace)
-  "Return a single entry from BACKTRACE which is snitch’s best
-guess for which function on the stack frame should be considered
+  "Determine entry in backtrace responsible for the event.
+
+Return a single entry from BACKTRACE which is snitch’s best guess
+for which function on the stack frame should be considered
 ’responsible’ for causing this event.  snitch uses this to assign
 one single function/file/package as the responsible party for an
 event, for use in filtering.

diff --git a/snitch-custom.el b/snitch-custom.el
line changes: +56/-36
index 27832d2..869ab15
--- a/snitch-custom.el
+++ b/snitch-custom.el
@@ -1,4 +1,4 @@
-;;; snitch-custom.el                       -*- lexical-binding: t; -*-
+;;; snitch-custom.el -- part of snitch     -*- lexical-binding: t; -*-
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 ;;
 ;; See snitch.el for full details.
@@ -50,7 +50,9 @@
 
 ;;;###autoload
 (defcustom snitch-lighter nil
-  "Text to display in mode-line when snitch is enabled, or nil to
+  "Text to display for snitch in mode-line.
+
+Text to display in mode-line when snitch is enabled, or nil to
 hide."
   :type 'string
   :group 'snitch)
@@ -64,8 +66,10 @@ hide."
 
 ;;;###autoload
 (defcustom snitch-log-policy '(all)
-  "Specifies types of actions that snitch should log.  Provided
-as a list of symbols defined in snitch-log-policies"
+  "Logging policies for snitch.
+
+Specifies types of actions that snitch should log.  Provided as a
+list of symbols defined in ‘snitch-log-policies’"
   :type '(repeat (choice (const all)
                          (const blocked)
                          (const allowed)
@@ -75,20 +79,24 @@ as a list of symbols defined in snitch-log-policies"
 
 ;;;###autoload
 (defcustom snitch-log-verbose nil
-  "Whether the log output should be extra verbose (pretty-printed
+  "Enable verbose logging for snitch.
+
+Whether the log output should be extra verbose (pretty-printed
 multi-line event logs)."
   :type 'boolean
   :group 'snitch-log)
 
 ;;;###autoload
 (defcustom snitch-log-buffer-max-lines 1000
-  "Maximum number of lines to keep in the snitch event log
+  "Max lines in snitch log buffer.
+
+Maximum number of lines to keep in the snitch event log
 buffer.  When it grows larger than this, the least recent lines
 are periodically truncated by a timer.
 
 Since trimming is timer-based, the log buffer can temporarily
 grow larger than the requested value.  It is only trimmed after a
-period of emacs idle time.
+period of Emacs idle time.
 
 Set to 0 for unlimited."
   :type 'number
@@ -96,7 +104,9 @@ Set to 0 for unlimited."
 
 ;;;###autoload
 (defcustom snitch-enable-notifications nil
-  "Whether snitch should raise notifications for each log
+  "Enable pop-up notifications for snitch events.
+
+Whether snitch should raise notifications for each log
 message, in addition to printing them in the log buffer.
 
 This feature requires the ‘alert’ package to be available.
@@ -117,20 +127,22 @@ the event object in ‘data’."
 
 ;;;###autoload
 (defcustom snitch-process-policy 'allow
-  "Default firewall policy for subprocesses.  When set to allow,
-exceptions can be specified in snitch-process-blacklist.  When
-set to deny, exceptions can be specified in
-snitch-process-whitelist."
+  "Default firewall policy for subprocesses.
+
+When set to allow, exceptions can be specified in
+‘snitch-process-blacklist’.  When set to deny, exceptions can be
+specified in ‘snitch-process-whitelist’."
   :type '(choice (const deny)
                  (const allow))
   :group 'snitch-policy)
 
 ;;;###autoload
 (defcustom snitch-network-policy 'allow
-  "Default firewall policy for network connections.  When set to
-allow, exceptions can be specified in snitch-network-blacklist.
-When set to deny, exceptions can be specified in
-snitch-network-whitelist."
+  "Default firewall policy for network connections.
+
+When set to allow, exceptions can be specified in
+‘snitch-network-blacklist’.  When set to deny, exceptions can be
+specified in ‘snitch-network-whitelist’."
   :type '(choice (const deny)
                  (const allow))
   :group 'snitch-policy)
@@ -145,9 +157,10 @@ snitch-network-whitelist."
 ;;;###autoload
 (defcustom snitch-network-blacklist
   '()
-  "A list of rules defining which network connections are
-forbidden when snitch.el is configured to allow connections by
-default.
+  "List of forbidden network connections.
+
+A list of rules defining which network connections are forbidden
+when snitch.el is configured to allow connections by default.
 
 See documentation of ‘snitch-process-whitelist’ for details."
   :group 'snitch-rules
@@ -157,9 +170,10 @@ See documentation of ‘snitch-process-whitelist’ for details."
 ;;;###autoload
 (defcustom snitch-network-whitelist
   '()
-  "A list of rules defining which network connections are
-permitted when snitch.el is configured to deny connections by
-default.
+  "List of permitted network connections.
+
+A list of rules defining which network connections are permitted
+when snitch.el is configured to deny connections by default.
 
 See documentation of ‘snitch-process-whitelist’ for details."
   :group 'snitch-rules
@@ -175,13 +189,15 @@ See documentation of ‘snitch-process-whitelist’ for details."
     ;; Example: block processes from system packages
     ;;(snitch-filter/src-pkg . (site-lisp))
 
-    ;; Example: block processes from emacs built-ins
+    ;; Example: block processes from Emacs built-ins
     ;;(snitch-filter/src-pkg . (built-in))
 
     ;; Example: block processes from an unknown user package
     ;;(snitch-filter/src-pkg . (user))
     )
-  "A list of rules defining which subprocess calls are forbidden
+  "List of forbidden subprocesses.
+
+A list of rules defining which subprocess calls are forbidden
 when snitch.el is configured to allow subprocesses by default.
 
 See documentation of ‘snitch-process-whitelist’ for details."
@@ -192,7 +208,9 @@ See documentation of ‘snitch-process-whitelist’ for details."
 ;;;###autoload
 (defcustom snitch-process-whitelist
   '()
-  "A list of rules defining which subprocess calls are permitted
+  "List of permitted subprocesses.
+
+A list of rules defining which subprocess calls are permitted
 when snitch.el is configured to deny subprocesses by default.
 
 If any filter returns true, the process is immediately allowed
@@ -205,7 +223,7 @@ form:
      (filter-fn2 . (arg2 arg3))
      (filter-fn3 . (arg4 arg5 arg6)))
 
-Each filter function must take a snitch-network-entry eieio
+Each filter function must take a ‘snitch-network-entry’ eieio
 object as its first parameter, and any number of subsequent
 arguments which are specified as the arguments in this alist.
 
@@ -328,15 +346,13 @@ Returning nil interrupts the block, allowing the event to pass."
 
 ;;;###autoload
 (defcustom snitch-init-hook '()
-  "Called immediately after snitch initializes and starts
-monitoring."
+  "Called immediately after snitch initializes."
   :group 'snitch-hooks
   :type 'hook)
 
 ;;;###autoload
 (defcustom snitch-deinit-hook '()
-  "Called immediately after snitch deinitializes and stops
-monitoring."
+  "Called immediately after snitch deinitializes."
   :group 'snitch-hooks
   :type 'hook)
 
@@ -403,15 +419,17 @@ timestamp and trailing newline intact."
 
 ;;;###autoload
 (defcustom snitch-trace-timers t
-  "Whether to decorate timer callbacks with backtraces, so snitch
+  "Enable tracing event sources through Emacs timers.
+
+Whether to decorate timer callbacks with backtraces, so snitch
 can identify the package source of an event that was scheduled on
 a timer.
 
-This must be configured before initializing snitch with
+This must be configured before initializing snitch with function
 ‘snitch-mode’.  If it is changed while snitch is running, call
 ‘snitch-restart’.
 
-Enabling this requires snitch to intercept all emacs timers.
+Enabling this requires snitch to intercept all Emacs timers.
 This can cause significant delays if there are very many timers,
 or very high-speed timers.  Use ‘snitch-timer-blacklist’ to
 exclude specific timers from snitch’s tracking.
@@ -451,9 +469,11 @@ snitch-monitor-unique-timer-fns’ for more."
 
 ;;;###autoload
 (defcustom snitch-print-timer-warnings t
-  "Whether snitch should output warnings when the functions
-tracking timer backtraces encounter an unusual situation, such as
-a missing timer or a timer that never fires.
+  "Print warnings related to snitch timer tracing.
+
+Whether snitch should output warnings when the functions tracking
+timer backtraces encounter an unusual situation, such as a
+missing timer or a timer that never fires.
 
 Note that misbehaved packages that cancel timers that aren't
 scheduled will trigger false-positive warnings."

diff --git a/snitch-filter.el b/snitch-filter.el
line changes: +1/-1
index 853265d..3b95c78
--- a/snitch-filter.el
+++ b/snitch-filter.el
@@ -1,4 +1,4 @@
-;;; snitch-filter.el                       -*- lexical-binding: t; -*-
+;;; snitch-filter.el -- part of snitch     -*- lexical-binding: t; -*-
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 ;;
 ;; See snitch.el for full details.

diff --git a/snitch-log.el b/snitch-log.el
line changes: +81/-43
index 69f96ce..e8ce83d
--- a/snitch-log.el
+++ b/snitch-log.el
@@ -1,4 +1,4 @@
-;;; snitch-log.el                          -*- lexical-binding: t; -*-
+;;; snitch-log.el -- part of snitch        -*- lexical-binding: t; -*-
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 ;;
 ;; See snitch.el for full details.
@@ -46,23 +46,28 @@
   "Name of the buffer for the log filter 'wizard' popup window.")
 
 (defvar snitch--log-filter-buffer nil
-  "Buffer in the log filter 'wizard' popup window")
+  "Buffer in the log filter 'wizard' popup window.")
 
 (defvar snitch--log-prune-timer nil
-  "Periodic timer to prune snitch log buffer to its maximum
+  "Timer to prune snitch log.
+
+Periodic timer to prune snitch log buffer to its maximum
 permitted size.")
 
 (defun snitch--exact-log-match (policies)
-  "Return true if any of policies are explicitly defined in
-snitch-log-policy."
+  "Check if log policies are explicitly enabled.
+
+Return true if any of POLICIES are explicitly defined in
+‘snitch-log-policy’."
   (seq-some 'identity
             (mapcar (lambda (l) (member l snitch-log-policy))
                     policies)))
 
 (defun snitch--log-policy-match (policies)
-  "Return true of any of the log policies in POLICIES are
-covered by one of the currently enabled policies in
-‘snitch-log-policy’.
+  "Check of current log policy matches given policies.
+
+Return true of any of the log policies in POLICIES are covered by
+one of the currently enabled policies in ‘snitch-log-policy’.
 
 This does not require exact matches.  For instance, if POLICIES
 contains ‘process-whitelisted’ and ‘snitch-log-policy’ contains
@@ -92,8 +97,10 @@ larger set including both ‘process-whitelisted’ and
          (member 'blocked snitch-log-policy)) t)))
 
 (defun snitch--pretty-obj-string (event)
-  "Return an event eieio object in a 'pretty-printed' form, which
-can be used to deserialize back into an object with eval."
+  "Pretty-print a snitch event.
+
+Take an event eieio object, EVENT, and return it as a
+'pretty-printed' string."
   ;; write eieio object out as a pretty string by redirecting
   ;; standard output stream to a function that consumes the output
   ;; char by char.  This must be reversed and concatenated to
@@ -107,7 +114,9 @@ can be used to deserialize back into an object with eval."
     pretty-obj))
 
 (defun snitch--propertize (logmsg event)
-  "Add text properties to LOGMSG with elements from EVENT.  This
+  "Add snitch event as properties to log message.
+
+Add text properties to LOGMSG with elements from EVENT.  This
 allows the log filter commands to re-assemble an event from its
 log message."
   (cond
@@ -134,11 +143,13 @@ log message."
                 'snitch-family (oref event family)))))
 
 (defun snitch--run-filter-log-hooks (logmsg)
-  "Run all hooks registered in ‘snitch-log-functions’ with the
-given log message.  Return the original log message if all hooks
-return t (or none are defined), or return nil or a modified new
-log string based on the first hook to return something other than
-t."
+  "Run hooks to filter snitch log messages.
+
+Run all hooks registered in ‘snitch-log-functions’ with the given
+log message, LOGMSG.  Return the original log message if all
+hooks return t (or none are defined), or return nil or a modified
+new log string based on the first hook to return something other
+than t."
   (if (null snitch-log-functions)
       logmsg
     (cl-loop for fn in snitch-log-functions with res = nil
@@ -149,9 +160,11 @@ t."
              finally return logmsg)))
 
 (defun snitch--log (evt-type event)
-  "Log a snitch event to the dedicated snitch firewall log
-buffer.  EVENT is an event object, and EVT-TYPE is any policy
-type from ‘snitch-log-policies’."
+  "Log a snitch event.
+
+Log a snitch event to the dedicated snitch firewall log buffer.
+EVENT is an event object, and EVT-TYPE is any policy type from
+‘snitch-log-policies’."
   (when (snitch--log-policy-match (list evt-type))
     (let* ((name (cond ((eq evt-type 'all) "event")
                        ((eq evt-type 'whitelisted) "whitelisted")
@@ -217,7 +230,9 @@ type from ‘snitch-log-policies’."
                :data event)))))
 
 (defun snitch--prune-log-buffer ()
-  "Prune the size of log buffer to at most
+  "Prune the snitch log buffer.
+
+Prune the size of log buffer to at most
 ‘snitch-log-buffer-max-lines’ lines long."
   ;; ensure timer is stopped.  it will be started again by the next
   ;; log event.  it’s wasteful to have a timer running when we know
@@ -240,14 +255,18 @@ type from ‘snitch-log-policies’."
           (setq buffer-read-only t))))))
 
 (defun snitch--maybe-start-log-prune-timer ()
-  "Start the snitch log pruning timer if it is not already
+  "Possibly start the snitch log pruning timer.
+
+Start the snitch log pruning timer if it is not already
 running."
   (unless snitch--log-prune-timer
     (snitch--start-log-prune-timer)))
 
 (defun snitch--start-log-prune-timer ()
-  "Start the snitch log pruning timer.  This is a non-repeating
-timer that calls snitch--prune-log-buffer after a period of
+  "Start the snitch log pruning timer.
+
+Start the snitch log pruning timer.  This is a non-repeating
+timer that calls ‘snitch--prune-log-buffer’ after a period of
 idle."
   (setq snitch--log-prune-timer
         (run-with-idle-timer 30 nil #'snitch--prune-log-buffer)))
@@ -269,7 +288,9 @@ idle."
 
 ;;;###autoload
 (defun snitch-filter-from-log ()
-  "Opens an interactive 'wizard' to create a new snitch
+  "Open snitch ’log filter’ wizard on selected log entry.
+
+Opens an interactive 'wizard' to create a new snitch
 whitelist/blacklist rule based on the event log under the cursor.
 
 To use the wizard, move the cursor over an item in the snitch
@@ -311,11 +332,14 @@ persistently as a customized variable."
                                         :args args)))))))
 
 (defun snitch--run-log-filter-wizard (event)
-  "Runs the snitch log filter 'wizard', an interactive popup
-window to help a user create a new blacklist or whitelist filter
-based on a log entry.  This function sets up the window,
-populates it, loops over user keypresses, and eventually saves
-the filter to the customization variable if appropriate."
+  "Run user interface for ’log filter’ wizard.
+
+Runs the snitch log filter 'wizard', an interactive popup window
+to help a user create a new blacklist or whitelist filter based
+on a log entry which has been converted back into a snitch event,
+EVENT.  This function sets up the window, populates it, loops
+over user keypresses, and eventually saves the filter to the
+customization variable if appropriate."
   ;; create buffer if needed
   (when (null snitch--log-filter-buffer)
     (snitch--init-log-filter-buffer))
@@ -384,19 +408,23 @@ the filter to the customization variable if appropriate."
         (customize-save-variable orig-list new-list)))))
 
 (defun snitch--log-filter-map-slot-from-key (map key)
-  "Given a map from ‘snitch--log-filter-map’, returns the slot
-matching to the given keypress, or nil."
+  "Return field matching key press in snitch log filter.
+
+Given a map from ‘snitch--log-filter-map’, MAP, returns the slot
+matching to the given keypress, KEY, or nil."
   (cl-loop for (slot . plist) in map
            when (string-equal (plist-get plist 'key) key)
            return slot
            finally return nil))
 
 (defun snitch--log-filter-map (event)
-  "Returns an alist of (SLOT . PLIST) pairs, where each PLIST
+  "Return a mapping of event fields to names and keymaps.
+
+Returns an alist of (SLOT . PLIST) pairs, where each PLIST
 contains a field name, a key to press to select it, and a
 ‘mnemonic’ version of the name with the key highlighted in square
 brackets.  The correct set of fields is returned based on the
-given event type.  All of this stuff is used to display the
+type of event in EVENT.  All of this stuff is used to display the
 fields, and to interpret which field to select when receiving
 user keypresses."
   (let ((common-alist nil)
@@ -429,11 +457,13 @@ user keypresses."
      (t common-alist))))
 
 (defun snitch--redraw-log-filter-buffer (evt selected)
-  "Draw the text contents of the log-filter menu based on the
-given event and list of currently selected fields.  Each field
-name is drawn on a separate line, along with its value in the
-current event.  The ‘mnemonic’ version of the field name is
-displayed, with the character to press surrounded by square
+  "Draw contents of snitch log filter buffer.
+
+Draw the text contents of the log-filter menu based on the given
+event, EVT, and list of currently selected fields, SELECTED.
+Each field name is drawn on a separate line, along with its value
+in the current event.  The ‘mnemonic’ version of the field name
+is displayed, with the character to press surrounded by square
 brackets.  Fields that are currently selected display in a
 different font."
   (with-current-buffer snitch--log-filter-buffer
@@ -458,8 +488,10 @@ different font."
       (goto-char (point-min)))))
 
 (defun snitch--init-log-filter-buffer ()
-  "Initialize buffer for displaying UI to generate a snitch
-filter from an existing log line."
+  "Initialize log filter UI.
+
+Initialize buffer for displaying UI to generate a snitch filter
+from an existing log line."
   ;; logic looted from which-key
   (unless (buffer-live-p snitch--log-filter-buffer)
     (setq snitch--log-filter-buffer
@@ -475,7 +507,9 @@ filter from an existing log line."
       (setq-local show-trailing-whitespace nil))))
 
 (defun snitch--hide-log-filter-window (buffer)
-  "Hide snitch log filter window, which is the window currently
+  "Hide snitch log filter UI.
+
+Hide snitch log filter window, which is the window currently
 displaying BUFFER."
   ;; based on which-key
   (when (buffer-live-p buffer)
@@ -483,7 +517,9 @@ displaying BUFFER."
     (run-hooks 'snitch-log-filter-window-close-hook)))
 
 (defun snitch--log-filter-window-size-to-fit (window)
-  "Resize log filter window, WINDOW, to a reasonable height and
+  "Resize snitch log filter window.
+
+Resize log filter window, WINDOW, to a reasonable height and
 maximum width."
   ;; based on which-key
   ;; cap at 30% of the vertical height
@@ -493,7 +529,9 @@ maximum width."
     (fit-window-to-buffer window max-height)))
 
 (defun snitch--show-log-filter-window ()
-  "Open or switch focus to the log filter window, resizing it as
+  "Show snitch log filter window.
+
+Open or switch focus to the log filter window, resizing it as
 necessary."
   ;; based on which-key
   (let* ((alist

diff --git a/snitch-timer.el b/snitch-timer.el
line changes: +88/-37
index 6a1e43e..bf4a676
--- a/snitch-timer.el
+++ b/snitch-timer.el
@@ -1,4 +1,4 @@
-;;; snitch-timer.el                        -*- lexical-binding: t; -*-
+;;; snitch-timer.el -- part of snitch      -*- lexical-binding: t; -*-
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 ;;
 ;; See snitch.el for full details.
@@ -42,15 +42,19 @@
 ;;; Code:
 
 (defvar snitch--timer-alist '()
-  "Cache all timers registered with emacs, along with their
+  "Cache of Emacs timers tracked by snitch.
+
+Cache all timers registered with Emacs, along with their
 backtrace and a timeout.  Stored as a list of (TIMER . METADATA)
 cons cell entries, where each METADATA item is a (BACKTRACE
-. TIMEOUT) cons cell.  TIMER is a standard emacs timer object,
-BACKTRACE is a snitch backtrace, and TIMEOUT is a standard emacs
+. TIMEOUT) cons cell.  TIMER is a standard Emacs timer object,
+BACKTRACE is a snitch backtrace, and TIMEOUT is a standard Emacs
 time object.")
 
 (defvar snitch--timer-removal-queue '()
-  "List of timers to be removed from snitch’s backtrace tracking
+  "List of Emacs timers to be removed from snitch’s tracking.
+
+List of timers to be removed from snitch’s backtrace tracking
 when the timer call stack is empty.  Timers are queued to be
 removed instead of removed immediately because of the (likely)
 possibility of recursive removals.  If the timer is removed deep
@@ -59,17 +63,23 @@ backtraces as the stack unwinds because the timer is already
 gone.")
 
 (defvar snitch--timer-count 0
-  "Total number of timers snitch has saved (timers registered
-with emacs and intercepted by snitch).")
+  "Total number of timers snitch has tracked.
+
+Total number of timers snitch has saved (timers registered with
+Emacs and intercepted by snitch).")
 
 (defvar snitch--timer-removed-count 0
-  "Total number of timers snitch has removed (timers fired or
+  "Total number of timers snitch has finished tracking.
+
+Total number of timers snitch has removed (timers fired or
 cancelled that snitch knew about).")
 
 (defvar snitch--timer-missed-count 0
-  "Total number of timers snitch has missed.  This is timers that
+  "Total number of timers that snitch failed to track.
+
+Total number of timers snitch has missed.  This is timers that
 are removed (cancelled or triggered) while not currently tracked
-in snitch--timer-alist.  This can happen naturally if snitch is
+in ‘snitch--timer-alist’.  This can happen naturally if snitch is
 started when timers already exist, but could also indicate bugs
 causing snitch to lose track of timers.")
 
@@ -79,27 +89,35 @@ Timer handlers often attempt to manually remove themselves,
 resulting in several calls to remove the same timer.")
 
 (defvar snitch--max-timer-backtraces 1000
-  "Maximum number of timer backtraces that snitch should keep
+  "Max number of timer backtrace snitch tracks at a time.
+
+Maximum number of timer backtraces that snitch should keep
 track of.  If more timers than this are started without ending,
 new timers are ignored.")
 
 (defvar snitch--save-unique-timer-fns nil
-  "While t, snitch saves a list of the unique functions
+  "Whether snitch saves names of timers tracked.
+
+While t, snitch saves a list of the unique functions
 registered as timers, along with a count of how many times they
 were seen.  This allows tracking which high-frequency timers are
-common in your emacs, so they can be added to the timer
+common in your Emacs, so they can be added to the timer
 blacklist.")
 
 (defvar snitch--unique-timer-fns '()
-  "A list of unique timer functions encountered, and how many
+  "List of unique timer functions snitch has tracked.
+
+A list of unique timer functions encountered, and how many
 times they were seen during the period that
-snitch--save-unique-timer-fns was t.")
+‘snitch--save-unique-timer-fns’ was t.")
 
 (defun snitch-monitor-unique-timer-fns (&optional time no-reset)
-  "Keeps a running count of each unique timer function that
-arrives during time period TIME.  After TIME has elapsed, prints
-all timers seen along with the number of times each was seen
-during the monitoring time period.
+  "Print names of timer functions snitch recently tracked.
+
+Keeps a running count of each unique timer function that arrives
+during time period TIME.  After TIME has elapsed, prints all
+timers seen along with the number of times each was seen during
+the monitoring time period.
 
 Each call to this function resets the seen timer list to empty.
 To continue capturing without clearing the list, set NO-RESET to
@@ -118,23 +136,32 @@ t."
               do (message "%s: %d" timer count)))))
 
 (defun snitch--timer-test-idle-timeout (time)
-  "Return t if an idle timer has timed out (current idle time
+  "Whether a tracked idle timer has timed out.
+
+Return t if an idle timer has timed out (current idle time
 greater than TIME)."
   (let ((idle (current-idle-time)))
     (when idle
       (time-less-p time idle))))
 
 (defun snitch--timer-test-timeout (time)
-  "Return t if a regular timer has timed out (current absolute time greater than TIME)."
+  "Whether a tracked normal timer has timed out.
+
+Return t if a regular timer has timed out (current absolute time
+greater than TIME)."
   (time-less-p time (current-time)))
 
 (defun snitch--timer-timeout (timer)
-  "Calculate a timeout for a timer, a few minutes longer than it
-is originally scheduled to fire."
+  "Calculate timeout period for a tracked timer.
+
+Calculate a timeout for a timer, TIMER, a few minutes longer than
+it is originally scheduled to fire."
   (time-add (timer--time timer) (time-convert (* 60 5))))
 
 (defun snitch--fn-repr (fn)
-  "Encode FN in a semi-human-readable form if it is a compiled
+  "Output function in human-readable format.
+
+Encode FN in a semi-human-readable form if it is a compiled
 function."
   (cond
    ((byte-code-function-p fn)
@@ -151,7 +178,9 @@ function."
    (t fn)))
 
 (defun snitch--save-timer-function (fn)
-  "Save timer function FN in SNITCH--UNIQUE-TIMER-FNS if it does
+  "Save recently tracked timer in cache.
+
+Save timer function FN in SNITCH--UNIQUE-TIMER-FNS if it does
 not already exist, otherwise increment its counter.  Byte
 compiled functions are stored as a hash, since their names are
 unknown."
@@ -163,12 +192,17 @@ unknown."
             (cons (cons fn-rep 1) snitch--unique-timer-fns)))))
 
 (defun snitch--save-timer-backtrace (orig-fn &rest args)
-  "Cache a timer and its associated backtrace.  This function is
-hooked around all functions that register new timers with emacs.
+  "Save timer and its backtrace in snitch’s timer cache.
+
+Cache a timer and its associated backtrace.  This function is
+hooked around all functions that register new timers with Emacs.
 It saves the backtrace and a timeout period for when snitch
 should stop listening for it in case the timer is somehow lost.
-It calls the original emacs timer registration function without
-modification and returns the result."
+It calls the original Emacs timer registration function without
+modification and returns the result.
+
+Always calls the original function ORIG-FN is called with its
+arguments ARGS unmodified."
   (let* ((bt (snitch--backtrace))
          ;;(bt '()) ;;(snitch--backtrace))
          (timer (nth 0 args))
@@ -192,7 +226,9 @@ modification and returns the result."
     result))
 
 (defun snitch--remove-timed-out-timers ()
-  "Iterate of all of snitch's saved timer backtraces and remove
+  "Remove tracked timers that have timed out.
+
+Iterate of all of snitch's saved timer backtraces and remove
 any that have timed out."
   (cl-loop for (timer . (_bt . timeout-fn)) in snitch--timer-alist
            when (funcall timeout-fn)
@@ -208,7 +244,9 @@ any that have timed out."
                      (delq match snitch--timer-alist))))))
 
 (defun snitch--remove-timers (timers)
-  "Remove all timers in TIMERS from the timer backtrace cache, if
+  "Remove a list of timers from snitch’s tracking.
+
+Remove all timers in TIMERS from the timer backtrace cache, if
 present."
   (let ((total-timers (length timers))
         (removed-timers 0))
@@ -231,11 +269,16 @@ present."
     (list removed-timers total-timers)))
 
 (defun snitch--remove-timer-backtrace (orig-fn timer)
-  "Remove a timer from snitch’s cache.  This function is wrapped
+  "Remove a timer from snitch’s tracking cache.
+
+Remove a timer from snitch’s cache.  This function is wrapped
 around ‘timer-event-handler’ and ‘cancel-timer’, triggering
 whenever a timer either fires or is explicitly cancelled.  It
 removes snitch’s decorated copy and calls the originally
-requested function as normal."
+requested function as normal.
+
+Always calls the original function ORIG-FN with its original
+argument, TIMER."
   (setq snitch--wrap-timer-depth (+ snitch--wrap-timer-depth 1))
   (let* ((result (apply orig-fn (list timer))))
     ;; TODO: this is probably wrong.  What if one timer removed a
@@ -279,7 +322,9 @@ requested function as normal."
                    #'snitch--remove-timer-backtrace))
 
 (defun snitch--register-timer-hooks ()
-  "Add timer hooks so snitch can provide backtraces all the way
+  "Register snitch’s timer tracing hooks.
+
+Add timer hooks so snitch can provide backtraces all the way
 to the source of whichever function registered the timer."
   (setq snitch--timer-alist '()
         snitch--timer-removal-queue '()
@@ -298,7 +343,9 @@ to the source of whichever function registered the timer."
                 #'snitch--remove-timer-backtrace))
 
 (defun snitch--debug-print-timer-state (&optional alist)
-  "Print current state of snitch’s timer tracing to the messages
+  "Print state of snitch’s timer tracing.
+
+Print current state of snitch’s timer tracing to the messages
 log.  If ALIST is t, also prints the currently cached timers."
   (interactive)
   (message "%s" (current-time-string))
@@ -312,7 +359,9 @@ log.  If ALIST is t, also prints the currently cached timers."
              do (message "timeout? %s" (funcall timeout-fn)))))
 
 (defun snitch--activate-timer-trace ()
-  "Activate snitch timer tracing by hooking the appropriate
+  "Activate snitch timer tracing.
+
+Activate snitch timer tracing by hooking the appropriate
 functions."
   (interactive)
   (snitch--register-timer-hooks))
@@ -323,7 +372,9 @@ functions."
   (snitch--remove-timer-hooks))
 
 (defun snitch--debug-test-print-timers ()
-  "Print snitch’s cached timers, and all of emacs’ currently
+  "Print snitch’s cached timer state.
+
+Print snitch’s cached timers, and all of Emacs’ currently
 registered timers."
   (cl-loop for (timer . meta) in snitch--timer-alist
            do

diff --git a/snitch.el b/snitch.el
line changes: +44/-26
index e1a90db..fe9a0f5
--- a/snitch.el
+++ b/snitch.el
@@ -1,4 +1,4 @@
-;;; snitch.el --- An emacs firewall        -*- lexical-binding: t; -*-
+;;; snitch.el --- An Emacs firewall        -*- lexical-binding: t; -*-
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 ;;
 ;; Copyright (C) 2020 Trevor Bentley
@@ -603,18 +603,20 @@ protocol family of the connection that snitch is considering.")
 
 (defconst snitch-source-package-types
   '(built-in site-lisp user)
-  "Possible types for a snitch event's package source, as found
-in the ‘src-pkg’ field of each event object.  In addition to
-these pre-defined types, any loaded package name (as a symbol) is
-a permitted type as well.
+  "Possible types for a snitch event's package source.
+
+Types are specified in the ‘src-pkg’ field of each event object.
+
+In addition to these pre-defined types, any loaded package
+name (as a symbol) is a permitted type as well.
 
   nil -- unknown source, including lambdas, closures, and
 compiled functions.
 
-  'built-in' -- package provided by emacs, and responds true to
+  'built-in' -- package provided by Emacs, and responds true to
 the ‘package-built-in-p’ function.
 
-  'site-lisp' -- package is found in one of the emacs common
+  'site-lisp' -- package is found in one of the Emacs common
 directories (i.e. a system-wide shared elisp directory), but does
 not report itself as a built-in.
 
@@ -667,9 +669,11 @@ were blocked by a blacklist rule")
     network-allowed
     network-whitelisted
     network-blacklisted)
-  "All of the logging policies for snitch.  Provide a list of
-these symbols to ‘snitch-log-policy’ to enable logging of events of
-the corresponding type.
+  "Permitted logging policies for snitch.
+
+Provide a list of these symbols to ‘snitch-log-policy’ to enable
+logging of events of the corresponding type.  Any combination can
+be combined, or use ‘all’ to include everything.
 
   'all' -- logs every event, before a decision is made.
 
@@ -706,8 +710,10 @@ whitelist rule or registered hook.")
 ;;
 
 (defun snitch--service-to-port (service)
-  "Convert SERVICE argument of ‘make-network-process’ into a symbol
-or number."
+  "Convert SERVICE into a symbol or number.
+
+SERVICE is the service field passed to ‘make-network-process’,
+representing the port to connect to."
   (cond
    ((symbolp service) service)
    ;; TODO: handle special service names, ex: "https"
@@ -723,12 +729,15 @@ or number."
                        list-hook-fns
                        default-evt-type
                        default-hook-fns)
-  "Return t if EVENT is to be filtered differently from the
-default policy, nil if default action is to be taken.  The choice
-of DECISION-LIST (whitelist or blacklist) and the event types
-(LIST-EVT-TYPE and DEFAULT-EVT-TYPE) determines whether default
-is block/allow.  Registered user hooks are called, and potentially
-alter the decision.
+  "Decide whether an event should use the default action.
+
+Return t if EVENT is to be filtered differently from the default
+policy, nil if default action is to be taken.  The choice of
+DECISION-LIST (whitelist or blacklist) and the event types
+\(LIST-EVT-TYPE and DEFAULT-EVT-TYPE) determines whether default
+is block/allow.  Registered user hooks are called, and
+potentially alter the decision: LIST-HOOK-FNS if the function was
+in the list, or DEFAULT-HOOK-FNS if it was not.
 
 This function only generates a decision.  It does not perform the
 actual block or pass action.
@@ -759,7 +768,9 @@ block action should be taken."
              t)))
 
 (defun snitch--wrap-internal (event prefix orig-fun args)
-  "Execute the wrapped function, ORIG-FUN with its original
+  "Perform snitch’s core firewall decision.
+
+Execute the wrapped function, ORIG-FUN with its original
 arguments ARGS if EVENT is allowed by default policy or
 whitelist.  PREFIX is the string 'process' or 'network' to
 indicate the type of event.  Registered hooks are called before
@@ -804,9 +815,11 @@ the globally configured log filters."
 
 
 (defun snitch--wrap-make-process (orig-fun &rest args)
-  "Wrap a call to make-process in the snitch firewall decision
+  "Wrap subprocesses with snitch firewall.
+
+Wrap a call to ‘make-process’ in the snitch firewall decision
 engine.  ORIG-FUN is called only if the snitch firewall rules
-permit it."
+permit it, receiving its default arguments ARGS."
   (let* ((bt (snitch--backtrace t))
          (caller (snitch--responsible-caller bt))
          (event (snitch-process-entry
@@ -820,9 +833,11 @@ permit it."
     (snitch--wrap-internal event "process" orig-fun args)))
 
 (defun snitch--wrap-make-network-process (orig-fun &rest args)
-  "Wrap a call to make-network-process in the snitch firewall
+  "Wrap network connections with snitch firewall.
+
+Wrap a call to ‘make-network-process’ in the snitch firewall
 decision engine.  ORIG-FUN is called only if the snitch firewall
-rules permit it."
+rules permit it, receiving its default arguments ARGS."
   (let* ((bt (snitch--backtrace t))
          (caller (snitch--responsible-caller bt))
          (event (snitch-network-entry
@@ -837,7 +852,9 @@ rules permit it."
     (snitch--wrap-internal event "network" orig-fun args)))
 
 (defun snitch--register-wrapper-fns ()
-  "Add snitch decision engine around the lowest-level emacs
+  "Enable snitch firewall wrapping functions.
+
+Add snitch decision engine around the lowest-level Emacs
 functions responsible for launching subprocesses and opening
 network connections."
   ;; lowest-level functions, implemented in C
@@ -886,8 +903,9 @@ may be lost in this process."
 
 ;;;###autoload
 (defun snitch-restart ()
-  "Restart the snitch firewall, unloading and reloading all
-hooks."
+  "Restart the snitch firewall.
+
+Unload and reload all hooks and timers."
   (interactive)
   (when (snitch--deinit)
     (snitch--init)))