- * \return The number of bytes that can be read from buf. Zero if the input
- * buffer queue is empty. In this case the value of \a bufp is undefined.
+ * If a buffer tree node needs more input data but can not consume the data it
+ * already has (because it might be needed again later) this function can be
+ * used instead of btr_next_buffer() to get a reference to the buffer obtained
+ * by skipping the given number of bytes. Skipped input bytes are not consumed.
+ *
+ * With a zero \a omit argument, this function is equivalent to \ref
+ * btr_next_buffer().
+ *
+ * \return Number of bytes in \a bufp. If there are less than or equal to \a
+ * omit many bytes available in the input queue of the buffer tree node pointed
+ * to by \a btrn, the function returns zero and the value of \a bufp is
+ * undefined.