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>

*** 429,455 ****
--- 429,482 ----
  static const zio_vsd_ops_t vdev_raidz_vsd_ops = {
          vdev_raidz_map_free_vsd,
          vdev_raidz_cksum_report
  };
  
+ /*
+  * Divides the IO evenly across all child vdevs; usually, dcols is
+  * the number of children in the target vdev.
+  */
  static raidz_map_t *
  vdev_raidz_map_alloc(zio_t *zio, uint64_t unit_shift, uint64_t dcols,
      uint64_t nparity)
  {
          raidz_map_t *rm;
+         /* The starting RAIDZ (parent) vdev sector of the block. */
          uint64_t b = zio->io_offset >> unit_shift;
+         /* The zio's size in units of the vdev's minimum sector size */
          uint64_t s = zio->io_size >> unit_shift;
+         /* The first column for this stripe. */
          uint64_t f = b % dcols;
+         /* The starting byte offset on each child vdev. */
          uint64_t o = (b / dcols) << unit_shift;
          uint64_t q, r, c, bc, col, acols, scols, coff, devidx, asize, tot;
  
+         /*
+          * "Quotient": The number of data sectors for this stripe on all but
+          * the "big column" child vdevs that also contain "remainder" data.
+          */
          q = s / (dcols - nparity);
+ 
+         /*
+          * "Remainder": The number of partial stripe data sectors in this I/O.
+          * This will add a sector to some, but not all, child vdevs.
+          */
          r = s - q * (dcols - nparity);
+ 
+         /* The number of "big columns" - those which contain remainder data. */
          bc = (r == 0 ? 0 : r + nparity);
+ 
+         /*
+          * The total number of data and parity sectors associated with
+          * this I/O.
+          */
          tot = s + nparity * (q + (r == 0 ? 0 : 1));
  
+         /* acols: The columns that will be accessed. */
+         /* scols: The columns that will be accessed or skipped. */
          if (q == 0) {
+                 /* Our I/O request doesn't span all child vdevs. */
                  acols = bc;
                  scols = MIN(dcols, roundup(bc, nparity + 1));
          } else {
                  acols = dcols;
                  scols = dcols;
*** 1519,1528 ****
--- 1546,1572 ----
          rc->rc_error = zio->io_error;
          rc->rc_tried = 1;
          rc->rc_skipped = 0;
  }
  
+ /*
+  * Start an IO operation on a RAIDZ VDev
+  *
+  * Outline:
+  * - For write operations:
+  *   1. Generate the parity data
+  *   2. Create child zio write operations to each column's vdev, for both
+  *      data and parity.
+  *   3. If the column skips any sectors for padding, create optional dummy
+  *      write zio children for those areas to improve aggregation continuity.
+  * - For read operations:
+  *   1. Create child zio read operations to each data column's vdev to read
+  *      the range of data required for zio.
+  *   2. If this is a scrub or resilver operation, or if any of the data
+  *      vdevs have had errors, then create zio read operations to the parity
+  *      columns' VDevs as well.
+  */
  static int
  vdev_raidz_io_start(zio_t *zio)
  {
          vdev_t *vd = zio->io_vd;
          vdev_t *tvd = vd->vdev_top;
*** 1859,1868 ****
--- 1903,1933 ----
          }
  
          return (ret);
  }
  
+ /*
+  * Complete an IO operation on a RAIDZ VDev
+  *
+  * Outline:
+  * - For write operations:
+  *   1. Check for errors on the child IOs.
+  *   2. Return, setting an error code if too few child VDevs were written
+  *      to reconstruct the data later.  Note that partial writes are
+  *      considered successful if they can be reconstructed at all.
+  * - For read operations:
+  *   1. Check for errors on the child IOs.
+  *   2. If data errors occurred:
+  *      a. Try to reassemble the data from the parity available.
+  *      b. If we haven't yet read the parity drives, read them now.
+  *      c. If all parity drives have been read but the data still doesn't
+  *         reassemble with a correct checksum, then try combinatorial
+  *         reconstruction.
+  *      d. If that doesn't work, return an error.
+  *   3. If there were unexpected errors or this is a resilver operation,
+  *      rewrite the vdevs that had errors.
+  */
  static void
  vdev_raidz_io_done(zio_t *zio)
  {
          vdev_t *vd = zio->io_vd;
          vdev_t *cvd;