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>

@@ -636,18 +636,27 @@
                 DB_DNODE_EXIT(db);
 
                 if (!havepzio)
                         err = zio_wait(zio);
         } else {
+                /*
+                 * Another reader came in while the dbuf was in flight
+                 * between UNCACHED and CACHED.  Either a writer will finish
+                 * writing the buffer (sending the dbuf to CACHED) or the
+                 * first reader's request will reach the read_done callback
+                 * and send the dbuf to CACHED.  Otherwise, a failure
+                 * occurred and the dbuf went to UNCACHED.
+                 */
                 mutex_exit(&db->db_mtx);
                 if (prefetch)
                         dmu_zfetch(&dn->dn_zfetch, db->db.db_offset,
                             db->db.db_size, TRUE);
                 if ((flags & DB_RF_HAVESTRUCT) == 0)
                         rw_exit(&dn->dn_struct_rwlock);
                 DB_DNODE_EXIT(db);
 
+                /* Skip the wait per the caller's request. */
                 mutex_enter(&db->db_mtx);
                 if ((flags & DB_RF_NEVERWAIT) == 0) {
                         while (db->db_state == DB_READ ||
                             db->db_state == DB_FILL) {
                                 ASSERT(db->db_state == DB_READ ||

@@ -1259,11 +1268,12 @@
         DB_DNODE_EXIT(db);
         return (dr);
 }
 
 /*
- * Return TRUE if this evicted the dbuf.
+ * Undirty a buffer in the transaction group referenced by the given
+ * transaction.  Return whether this evicted the dbuf.
  */
 static boolean_t
 dbuf_undirty(dmu_buf_impl_t *db, dmu_tx_t *tx)
 {
         dnode_t *dn;

@@ -2220,24 +2230,27 @@
         mutex_enter(&db->db_mtx);
 
         ASSERT(db->db_level > 0);
         DBUF_VERIFY(db);
 
+        /* Read the block if it hasn't been read yet. */
         if (db->db_buf == NULL) {
                 mutex_exit(&db->db_mtx);
                 (void) dbuf_read(db, NULL, DB_RF_MUST_SUCCEED);
                 mutex_enter(&db->db_mtx);
         }
         ASSERT3U(db->db_state, ==, DB_CACHED);
         ASSERT(db->db_buf != NULL);
 
         DB_DNODE_ENTER(db);
         dn = DB_DNODE(db);
+        /* Indirect block size must match what the dnode thinks it is. */
         ASSERT3U(db->db.db_size, ==, 1<<dn->dn_phys->dn_indblkshift);
         dbuf_check_blkptr(dn, db);
         DB_DNODE_EXIT(db);
 
+        /* Provide the pending dirty record to child dbufs */
         db->db_data_pending = dr;
 
         mutex_exit(&db->db_mtx);
         dbuf_write(dr, db->db_buf, tx);
 

@@ -2620,10 +2633,11 @@
         mutex_exit(&db->db_mtx);
 
         dbuf_write_done(zio, NULL, db);
 }
 
+/* Issue I/O to commit a dirty buffer to disk. */
 static void
 dbuf_write(dbuf_dirty_record_t *dr, arc_buf_t *data, dmu_tx_t *tx)
 {
         dmu_buf_impl_t *db = dr->dr_dbuf;
         dnode_t *dn;

@@ -2654,15 +2668,23 @@
                         }
                 }
         }
 
         if (parent != dn->dn_dbuf) {
+                /* Our parent is an indirect block. */
+                /* We have a dirty parent that has been scheduled for write. */
                 ASSERT(parent && parent->db_data_pending);
+                /* Our parent's buffer is one level closer to the dnode. */
                 ASSERT(db->db_level == parent->db_level-1);
+                /*
+                 * We're about to modify our parent's db_data by modifying
+                 * our block pointer, so the parent must be released.
+                 */
                 ASSERT(arc_released(parent->db_buf));
                 zio = parent->db_data_pending->dr_zio;
         } else {
+                /* Our parent is the dnode itself. */
                 ASSERT((db->db_level == dn->dn_phys->dn_nlevels-1 &&
                     db->db_blkid != DMU_SPILL_BLKID) ||
                     (db->db_blkid == DMU_SPILL_BLKID && db->db_level == 0));
                 if (db->db_blkid != DMU_SPILL_BLKID)
                         ASSERT3P(db->db_blkptr, ==,