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>
Reviewed by:    Eric Schrock <eric.schrock@delphix.com>

*** 252,262 ****
--- 252,273 ----
          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,2960 ****
--- 2962,2975 ----
                                  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,3152 ****
          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.
   * 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)
--- 3156,3167 ----
          kmem_cache_free(buf_cache, buf);
          return (1);
  }
  
  /*
!  * 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)