more comments

apps/choo/bootstrap/kernel.hoon

@@ -633,8 +633,10 @@
       ~>  %bout
       ?:  ?=(%hoon -.leaf.n)
         ::
-        ::  We append the honc (hoon stdlib) to the end of the vase
+        ::  We append the honc (hoon.hoon) to the end of the vase
         ::  because imports have higher precedence when resolving faces.
+        ::  To avoid shadowing issues with hoon.hoon, attach faces to your
+        ::  imports or avoid shadowed names altogether.
         (swet (slew dep-vaz honc) hoon.leaf.n)
       =>  octs=!>(octs.leaf.n)
       |.(octs)
@@ -650,8 +652,7 @@
       (~(got by bc) dep-hash)
     ~&  >  attaching-face+face.r
     ::
-    ::  Ford imports are included in the order that
-    ::  they appear in the deps.
+    ::  Ford imports are included in the order that they appear in the deps.
     (slew vaz (label-vase dep-vaz face.r))
   ::
   ::  $label-vase: label a (trap vase) with a face