additions to metadata object api: more vorbiscomment functions, trailing-null on vorbis comment field values enforced everywhere

1 files changed, 9 insertions, 0 deletions

diff --git a/include/FLAC/format.h b/include/FLAC/format.h
index e003c34f..d4e6bcac 100644
--- a/include/FLAC/format.h
+++ b/include/FLAC/format.h
@@ -583,6 +583,15 @@ typedef struct {
 
 
 /** Vorbis comment entry structure used in VORBIS_COMMENT blocks.  (c.f. <A HREF="../format.html#metadata_block_vorbis_comment">format specification</A>)
+ *
+ *  For convenience, the APIs maintain a trailing NUL character at the end of
+ *  \a entry which is not counted toward \a length or stored in the stream,
+ *  i.e.
+ *  \code strlen(entry) == length \endcode
+ *
+ *  It's recommended but not required for users to follow this convention as
+ *  well when dealing directly with FLAC__StreamMetadata_VorbisComment_Entry
+ *  as it makes dealing with plain strings easier.
  */
 typedef struct {
 	FLAC__uint32 length;