Index: main/org-autofocus.el
===================================================================
--- main/org-autofocus.el	(revision main,14)
+++ main/org-autofocus.el	(revision main,15)
@@ -8,4 +8,59 @@
 
 ;;; Commentary:
+
+;; This minor mode works primarily by lightly analyzing the Org Agenda todo list
+;; and adding some extra text properties, and by the addition of a TOUCHED
+;; property to tasks' property drawers.
+;;
+;; Tasks are identified by looking at the beginning of a line for the TYPE
+;; property that Org adds.  The code does /not/ verify that the property's value
+;; is "todo".  It's assumed that a task runs from the beginning of a line to the
+;; end of the same line.
+;;
+;; A task is "dotted" or "marked" by setting the DISPLAY properties of the first
+;; character of the line to "*".
+;;
+;; A range of tasks is hidden by setting the INVISIBLE property of the entire
+;; line to T.  Because this hides the newline, the range of hidden tasks
+;; actually appears at the beginning of the line for the following unhidden
+;; task; see ORG-AF--BEG-OF-TASK.
+;;
+;; A marked task is dimmed by adding an overlay with FACE set to
+;; 'ORG-AGENDA-DIMMED-TODO-FACE.
+;;
+;; Properties are added as one property representing the state
+;; (e.g. ORG-AF-MARKED) set to T for easy property testing, and the CATEGORY
+;; property set to the state (e.g. 'ORG-AF-MARKED) to handle the actual visual
+;; characteristics.  See variable ORG-AF-MARKED and following functions for an
+;; example.
+;;
+;; Tasks are sorted according to the value of the TOUCHED property;
+;; least-recently-touched tasks are followed by most-recently-touched tasks.
+;; Any task that doesn't already have the property is touched at the time of
+;; sorting.
+;;
+;; The user may mark a task by pressing "."; all tasks between it and the
+;; previous marked task will be hidden, and all previous marked tasks dimmed.
+;; The idea is that hidden and dimmed tasks are not to be manipulated any
+;; further, until subsquent marked tasks have been handled in some way.
+;;
+;; The user may defer a task by pressing "d"; the task will be unmarked,
+;; touched, and sorted to the end.
+;;
+;; Finally, the user may complete a task by pressing "c" or "t"; the task will
+;; be unmarked, completed by Org's code, touched, and sorted to the end.
+
+;;; Known issues:
+
+;; Keymaps and commands are not sufficiently controlled.  A user may manipulate
+;; a task in a way this minor mode doesn't handle.  A user may also manipulate
+;; tasks that are dimmed.
+
+;; Redo'ing the agenda loses the minor mode; it's necessary to run ORG-AUTOFOCUS
+;; every time the minor mode is desired.
+
+;; I haven't yet found a way to enable this minor mode without using a command
+;; that wraps the call to ORG-AGENDA with some overriding bindings in place.
+;; This is the primary reason that redo isn't supported.
 
 ;;; Code: