-/*
- * dbuf_map, dbuf_delete
- *
- * These functions are meant to be used in pairs and offer a more efficient
- * way of emptying the buffer than the normal 'dbuf_get' would allow--less
- * copying needed.
- *
- * map returns a pointer to a largest contiguous section
- * of bytes in front of the buffer, the length of the
- * section is placed into the indicated "long int"
- * variable. Returns NULL *and* zero length, if the
- * buffer is empty.
- *
- * delete removes the specified number of bytes from the
- * front of the buffer releasing any memory used for them.
- *
- * Example use (ignoring empty condition here ;)
- *
- * buf = dbuf_map(&dyn, &count);
- * <process N bytes (N <= count) of data pointed by 'buf'>
- * dbuf_delete(&dyn, N);
- *
- * Note: delete can be used alone, there is no real binding
- * between map and delete functions...
- *
- * dyn: Dynamic buffer header
- * length: Return number of bytes accessible
+/** Get the first contiguous block of data from a DBuf.
+ * Generally a call to dbuf_map(dyn, &count) will be followed with a
+ * call to dbuf_delete(dyn, count).
+ * @param[in] dyn DBuf to retrieve data from.
+ * @param[out] length Receives number of bytes in block.
+ * @return Pointer to start of block (or NULL if the first block is empty).