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>

*** 407,416 ****
--- 407,418 ----
   * data.  As with any normal buffer, you must call dmu_buf_read() to
   * read db_data, dmu_buf_will_dirty() before modifying it, and the
   * object must be held in an assigned transaction before calling
   * dmu_buf_will_dirty.  You may use dmu_buf_set_user() on the bonus
   * buffer as well.  You must release your hold with dmu_buf_rele().
+  *
+  * Returns ENOENT, EIO, or 0.
   */
  int dmu_bonus_hold(objset_t *os, uint64_t object, void *tag, dmu_buf_t **);
  int dmu_bonus_max(void);
  int dmu_set_bonus(dmu_buf_t *, int, dmu_tx_t *);
  int dmu_set_bonustype(dmu_buf_t *, dmu_object_type_t, dmu_tx_t *);
*** 662,673 ****
--- 664,681 ----
   * Return 0 on success or ENOENT if object is not allocated.
   *
   * If doi is NULL, just indicates whether the object exists.
   */
  int dmu_object_info(objset_t *os, uint64_t object, dmu_object_info_t *doi);
+ /* Like dmu_object_info, but faster if you have a held dnode in hand. */
  void dmu_object_info_from_dnode(struct dnode *dn, dmu_object_info_t *doi);
+ /* Like dmu_object_info, but faster if you have a held dbuf in hand. */
  void dmu_object_info_from_db(dmu_buf_t *db, dmu_object_info_t *doi);
+ /*
+  * Like dmu_object_info_from_db, but faster still when you only care about
+  * the size.  This is specifically optimized for zfs_getattr().
+  */
  void dmu_object_size_from_db(dmu_buf_t *db, uint32_t *blksize,
      u_longlong_t *nblk512);
  
  typedef struct dmu_objset_stats {
          uint64_t dds_num_clones; /* number of clones of this */