Better explain usage of CBB_flush
The high-level documentation for CBB describes using CBB_flush when a
child goes out of scope, but the function level documentation for
CBB_flush is less clear that CBB_flush will result in the CBB being
safe to use after the children go out of scope.
Change-Id: I58bf9e59a87d2be31a969097455aeeae6381efb3
Reviewed-on: https://boringssl-review.googlesource.com/11261
Reviewed-by: David Benjamin <davidben@google.com>
diff --git a/include/openssl/bytestring.h b/include/openssl/bytestring.h
index 2985268..ceb036e 100644
--- a/include/openssl/bytestring.h
+++ b/include/openssl/bytestring.h
@@ -327,8 +327,10 @@
OPENSSL_EXPORT int CBB_finish(CBB *cbb, uint8_t **out_data, size_t *out_len);
/* CBB_flush causes any pending length prefixes to be written out and any child
- * |CBB| objects of |cbb| to be invalidated. It returns one on success or zero
- * on error. */
+ * |CBB| objects of |cbb| to be invalidated. This allows |cbb| to continue to be
+ * used after the children go out of scope, e.g. when local |CBB| objects are
+ * added as children to a |CBB| that persists after a function returns. This
+ * function returns one on success or zero on error. */
OPENSSL_EXPORT int CBB_flush(CBB *cbb);
/* CBB_data returns a pointer to the bytes written to |cbb|. It does not flush
