- * The "in" xbuf is altered to update "pos" and "len". The "out" xbuf has
- * data appended, and its "len" incremented. If ICB_EXPAND_OUT is set in
- * "flags", the "out" xbuf will also be allocated if empty, and expanded if
- * too small (so E2BIG will not be returned). If ICB_INCLUDE_BAD is set in
- * "flags", any badly-encoded chars are included verbatim in the "out" xbuf,
- * so EILSEQ will not be returned. Likewise for ICB_INCLUDE_INCOMPLETE with
- * respect to an incomplete multi-byte char at the end, which ensures that
- * EINVAL is not returned. If ICB_INIT is set, the iconv() conversion state
- * is initialized prior to processing the characters. */
+ * The "in" xbuf is altered to update ".pos" and ".len". The "out" xbuf has
+ * data appended, and its ".len" incremented (see below for a ".size" note).
+ *
+ * If ICB_CIRCULAR_OUT is set in "flags", the chars going into the "out" xbuf
+ * can wrap around to the start, and the xbuf may have its ".size" reduced
+ * (presumably by 1 byte) if the iconv code doesn't have space to store a
+ * multi-byte character at the physical end of the ".buf" (though no reducing
+ * happens if ".pos" is <= 1, since there is no room to wrap around).
+ *
+ * If ICB_EXPAND_OUT is set in "flags", the "out" xbuf will be allocated if
+ * empty, and (as long as ICB_CIRCULAR_OUT is not set) expanded if too small.
+ * This prevents the return of E2BIG (except for a circular xbuf).
+ *
+ * If ICB_INCLUDE_BAD is set in "flags", any badly-encoded chars are included
+ * verbatim in the "out" xbuf, so EILSEQ will not be returned.
+ *
+ * If ICB_INCLUDE_INCOMPLETE is set in "flags", any incomplete multi-byte
+ * chars are included, which ensures that EINVAL is not returned.
+ *
+ * If ICB_INIT is set, the iconv() conversion state is initialized prior to
+ * processing the characters. */