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,653 ****
--- 636,662 ----
                  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,1269 ****
          DB_DNODE_EXIT(db);
          return (dr);
  }
  
  /*
!  * Return TRUE if this evicted the dbuf.
   */
  static boolean_t
  dbuf_undirty(dmu_buf_impl_t *db, dmu_tx_t *tx)
  {
          dnode_t *dn;
--- 1268,1279 ----
          DB_DNODE_EXIT(db);
          return (dr);
  }
  
  /*
!  * 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,2243 ****
--- 2230,2256 ----
          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,2629 ****
--- 2633,2643 ----
          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,2668 ****
--- 2668,2690 ----
                          }
                  }
          }
  
          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, ==,