diff --git a/action.lisp b/action.lisp
index 157f88a6c8bab9bcb9ac1eb5426f5509d3f21aad..842e6b891f42910bf3568d31073d1e5c02407bf7 100644
--- a/action.lisp
+++ b/action.lisp
@@ -115,7 +115,14 @@ You can put together sentences using this phrase."))
         and each <component> is a component designator with respect to
         FIND-COMPONENT in the context of the COMPONENT argument,
         and means that the component depends on
-        <operation> having been performed on each <component>; or
+        <operation> having been performed on each <component>;
+
+        [Note: an <operation> is an operation designator -- it can be either an
+        operation name or an operation object.  Similarly, a <component> may be
+        a component name or a component object.  Finally, the degenerate case of
+        (<operation>) is treated as a no-op.]
+
+      or
 
       (FEATURE <feature>), which means that the component depends
         on the <feature> expression satisfying FEATUREP.
@@ -188,10 +195,12 @@ each of its declared dependencies must first be loaded as by LOAD-OP."))
     (:documentation "A SELFWARD-OPERATION depends on another operation on the same component.
 I.e., if O is a SELFWARD-OPERATION, and its SELFWARD-OPERATION designates a list of operations L,
 then the action (O . C) of O on component C depends on each (S . C) for S in L.
+E.g. before a component may be loaded by LOAD-OP, it must have been compiled by COMPILE-OP.
 A operation-designator designates a singleton list of the designated operation;
 a list of operation-designators designates the list of designated operations;
-NIL is not a valid operation designator in that context.
-E.g. before a component may be loaded by LOAD-OP, it must have been compiled by COMPILE-OP."))
+NIL is not a valid operation designator in that context.  Note that orderings between 
+the operations in a list of SELWARD-OPERATION should be indicated separately in order
+that they be scheduled properly."))
   (defmethod component-depends-on ((o selfward-operation) (c component))
     `(,@(loop :for op :in (ensure-list (selfward-operation o))
               :collect `(,op ,c))
diff --git a/bundle.lisp b/bundle.lisp
index 9c3bfe3c033d4420d2b38d283b51242676bfdad7..d68d378c6cf2b59d4de8bf990886b939ecbe5f54 100644
--- a/bundle.lisp
+++ b/bundle.lisp
@@ -64,7 +64,12 @@
     ((selfward-operation :initform '(fasl-op lib-op) :allocation :class))
     (:documentation "produce fasl and asd files for the system"))
 
-  (defclass monolithic-op (operation) ()) ;; operation on a system and its dependencies
+  (defclass monolithic-op (operation) ()
+    (:documentation "A MONOLITHIC operation operates on a system *and all of its
+dependencies*.  So, for example, a monolithic concatenate operation will
+concatenate together a system's components and all of its dependencies, but a
+simple concatenate operation will concatenate only the components of the system
+itself.")) ;; operation on a system and its dependencies
 
   (defclass monolithic-bundle-op (monolithic-op bundle-op)
     ((prologue-code :accessor monolithic-op-prologue-code)
@@ -72,7 +77,8 @@
 
   (defclass monolithic-bundle-compile-op (monolithic-bundle-op bundle-compile-op)
     ()
-    (:documentation "Abstract operation for ways to bundle the outputs of compiling *Lisp* files over all systems"))
+    (:documentation "Abstract operation for ways to bundle the outputs of compiling
+*Lisp* files over a system, and all of its dependencies."))
 
   (defclass monolithic-binary-op (monolithic-op binary-op)
     ((selfward-operation :initform '(monolithic-fasl-op monolithic-lib-op) :allocation :class))
diff --git a/component.lisp b/component.lisp
index 83f13edecdca8ae62c119c2a18a8c1b1217816a8..f8a5f26a767901f38362b9a258155455074a3048 100644
--- a/component.lisp
+++ b/component.lisp
@@ -142,6 +142,9 @@ another pathname in a degenerate way."))
       :initarg :build-operation :initform nil :reader component-build-operation)))
 
   (defun component-find-path (component)
+    "Return a path from a root system to the COMPONENT.
+The return value is a list of component NAMES; a list of
+strings."
     (check-type component (or null component))
     (reverse
      (loop :for c = component :then (component-parent c)
@@ -160,7 +163,9 @@ another pathname in a degenerate way."))
 ;;;; Component hierarchy within a system
 ;; The tree typically but not necessarily follows the filesystem hierarchy.
 (with-upgradability ()
-  (defclass child-component (component) ())
+  (defclass child-component (component) ()
+    (:documentation "A CHILD-COMPONENT is a component that may be part of
+a PARENT-COMPONENT."))
 
   (defclass file-component (child-component)
     ((type :accessor file-type :initarg :type))) ; no default
@@ -189,7 +194,9 @@ another pathname in a degenerate way."))
      (default-component-class
       :initform nil
       :initarg :default-component-class
-      :accessor module-default-component-class))))
+      :accessor module-default-component-class)))
+  (:documentation "A PARENT-COMPONENT is a component that may have
+children."))
 
 (with-upgradability ()
   (defun compute-children-by-name (parent &key only-if-needed-p)
diff --git a/lisp-action.lisp b/lisp-action.lisp
index 6adc154f4e2a24b2e3822021fbb0971f3ae91518..d4ce3626228960cfd4d2a3ae25ab2c8c4a21b74a 100644
--- a/lisp-action.lisp
+++ b/lisp-action.lisp
@@ -38,7 +38,9 @@
 ;;; Our default operations: loading into the current lisp image
 (with-upgradability ()
   (defclass prepare-op (upward-operation sideway-operation)
-    ((sideway-operation :initform 'load-op :allocation :class)))
+    ((sideway-operation :initform 'load-op :allocation :class))
+    (:documentation "Load the necessary dependencies for the COMPONENT to which we apply
+the PREPARE-OP."))
   (defclass load-op (basic-load-op downward-operation sideway-operation selfward-operation)
     ;; NB: even though compile-op depends on prepare-op it is not needed-in-image-p,
     ;; so we need to directly depend on prepare-op for its side-effects in the current image.
diff --git a/operate.lisp b/operate.lisp
index c8c8f66cf13a489c98268294d7f6613de501ede7..a4b42762c01d4e52086fcb394eba800d9938f2c2 100644
--- a/operate.lisp
+++ b/operate.lisp
@@ -23,11 +23,11 @@
 
 1. It creates an instance of OPERATION-CLASS using any keyword parameters as initargs.
 2. It finds the  asdf-system specified by SYSTEM (possibly loading it from disk).
-3. It then calls TRAVERSE with the operation and system as arguments
+3. It then calls MAKE-PLAN with the operation and system as arguments
 
-The traverse operation is wrapped in WITH-COMPILATION-UNIT and error handling code.
-If a VERSION argument is supplied, then operate also ensures that the system found
-satisfies it using the VERSION-SATISFIES method.
+The operation of making a plan is wrapped in WITH-COMPILATION-UNIT and error
+handling code.  If a VERSION argument is supplied, then operate also ensures
+that the system found satisfies it using the VERSION-SATISFIES method.
 
 Note that dependencies may cause the operation to invoke other operations on the system
 or its components: the new operations will be created with the same initargs as the original one.
diff --git a/operation.lisp b/operation.lisp
index 6949114fc6ab7a7a97595ba9359f93ccb7bae3b1..41fbacbc4795c7cc31e38daa422752eb30687e61 100644
--- a/operation.lisp
+++ b/operation.lisp
@@ -58,6 +58,11 @@
     (declare (ignorable context))
     nil)
 
+  ;; build op was intended to be the master, default operation on a system
+  ;; (LOAD-OP typically serves that function now).  This feature has not yet
+  ;; been fully implemented yet.
+  ;; This is a path forward, but is not backwardly compatible, and is not used
+  ;; yet. [2014/01/26:rpg]
   (defclass build-op (operation) ()))
 
 
diff --git a/plan.lisp b/plan.lisp
index a7cfb1fd8423429d574c1dd0ad4a03cdebc68eb1..75d4a93164a3b5f65faebbdb2d64507edc330b2b 100644
--- a/plan.lisp
+++ b/plan.lisp
@@ -302,9 +302,16 @@ the action of OPERATION on COMPONENT in the PLAN"))
 
   (defmethod traverse-action (plan operation component needed-in-image-p)
     (block nil
+      ;; ACTION-VALID-P among other things, handles forcing logic, including
+      ;; FORCE-NOT.
       (unless (action-valid-p plan operation component) (return nil))
+      ;; the following is needed by POIU, which tracks a dependency graph,
+      ;; instead of just a dependency order as in vanilla ASDF
       (plan-record-dependency plan operation component)
+      ;; needed in image distinguishes b/w things that must happen in the
+      ;; current image and those things that simply need to have been done.
       (let* ((aniip (needed-in-image-p operation component))
+             ;; effectively needed in image
              (eniip (and aniip needed-in-image-p))
              (status (plan-action-status plan operation component)))
         (when (and status (or (action-done-p status) (action-planned-p status) (not eniip)))
@@ -402,6 +409,9 @@ the action of OPERATION on COMPONENT in the PLAN"))
 
 
 ;;;; Incidental traversals
+
+;;; Making a FILTERED-SEQUENTIAL-PLAN can be used to, e.g., all of the source
+;;; files required by a bundling operation.
 (with-upgradability ()
   (defclass filtered-sequential-plan (sequential-plan)
     ((action-filter :initform t :initarg :action-filter :reader plan-action-filter)
diff --git a/upgrade.lisp b/upgrade.lisp
index d6cfcf4b0a32d1ec2df58eef6413d7b36a2d18a4..fa0586de3ab1b3676c02cac45820ba1e4118f4cb 100644
--- a/upgrade.lisp
+++ b/upgrade.lisp
@@ -51,6 +51,8 @@ You can compare this string with e.g.: (ASDF:VERSION-SATISFIES (ASDF:ASDF-VERSIO
   (defun upgrading-p ()
     (and *previous-asdf-versions* (not (equal *asdf-version* (first *previous-asdf-versions*)))))
   (defmacro when-upgrading ((&key (upgrading-p '(upgrading-p)) when) &body body)
+    "A wrapper macro for code that should only be run when upgrading a 
+previously-loaded version of ASDF."
     `(with-upgradability ()
        (when (and ,upgrading-p ,@(when when `(,when)))
          (handler-bind ((style-warning #'muffle-warning))