3741 zfs needs better comments
Submitted by:   Will Andrews <willa@spectralogic.com>
Submitted by:   Justin Gibbs <justing@spectralogic.com>
Submitted by:   Alan Somers <alans@spectralogic.com>
Reviewed by:    Matthew Ahrens <mahrens@delphix.com>

@@ -252,11 +252,22 @@
         kstat_named_t arcstat_mru_ghost_hits;
         kstat_named_t arcstat_mfu_hits;
         kstat_named_t arcstat_mfu_ghost_hits;
         kstat_named_t arcstat_deleted;
         kstat_named_t arcstat_recycle_miss;
+        /*
+         * Number of buffers that could not be evicted because the hash lock
+         * was held by another thread.  The lock may not necessarily be held
+         * by something using the same buffer, since hash locks are shared
+         * by multiple buffers.
+         */
         kstat_named_t arcstat_mutex_miss;
+        /*
+         * Number of buffers skipped because they have I/O in progress, are
+         * indrect prefetch buffers that have not lived long enough, or are
+         * not from the spa we're trying to evict from.
+         */
         kstat_named_t arcstat_evict_skip;
         kstat_named_t arcstat_evict_l2_cached;
         kstat_named_t arcstat_evict_l2_eligible;
         kstat_named_t arcstat_evict_l2_ineligible;
         kstat_named_t arcstat_hash_elements;

@@ -2951,10 +2962,14 @@
                                 vd = NULL;
                 }
 
                 mutex_exit(hash_lock);
 
+                /*
+                 * At this point, we have a level 1 cache miss.  Try again in
+                 * L2ARC if possible.
+                 */
                 ASSERT3U(hdr->b_size, ==, size);
                 DTRACE_PROBE4(arc__miss, arc_buf_hdr_t *, hdr, blkptr_t *, bp,
                     uint64_t, size, zbookmark_t *, zb);
                 ARCSTAT_BUMP(arcstat_misses);
                 ARCSTAT_CONDSTAT(!(hdr->b_flags & ARC_PREFETCH),

@@ -3141,12 +3156,12 @@
         kmem_cache_free(buf_cache, buf);
         return (1);
 }
 
 /*
- * Release this buffer from the cache.  This must be done
- * after a read and prior to modifying the buffer contents.
+ * Release this buffer from the cache, making it an anonymous buffer.  This
+ * must be done after a read and prior to modifying the buffer contents.
  * If the buffer has more than one reference, we must make
  * a new hdr for the buffer.
  */
 void
 arc_release(arc_buf_t *buf, void *tag)