[xiph-commits] r2959 - liboggz/trunk/include/oggz

[conrad at svn.annodex.net]

Author: conrad
Date: 2007-06-16 20:14:36 -0700 (Sat, 16 Jun 2007)
New Revision: 2959

Modified:
   liboggz/trunk/include/oggz/oggz_comments.h
Log:
clarify use of FLAC_final_metadata_block in oggz_comment_generate()


Modified: liboggz/trunk/include/oggz/oggz_comments.h
===================================================================
--- liboggz/trunk/include/oggz/oggz_comments.h	2007-06-16 12:00:31 UTC (rev 2958)
+++ liboggz/trunk/include/oggz/oggz_comments.h	2007-06-17 03:14:36 UTC (rev 2959)
@@ -243,22 +243,22 @@
  * \param serialno Identify a logical bitstream within \a oggz
  * \param packet_type Type of comment packet to generate,
  * FLAC, OggPCM, Speex, Theora and Vorbis are supported
- * \param FLAC_final_metadata_block Non-zero if there are no FLAC
- * metadata blocks to follow (see note)
+ * \param FLAC_final_metadata_block Set this to zero unless the packet_type is
+ * FLAC, and there are no further metadata blocks to follow. See note below
+ * for details.
  * \returns A comment packet for the stream. When no longer needed it
  * should be freed with oggz_packet_destroy().
  * \retval NULL content type does not support comments, not enough memory
  * or comment was too long for FLAC
- * \note FLAC users: FLAC streams may contain multiple metadata blocks
- * of different types. When encapsulated in Ogg the first of these must
- * be a Vorbis comment packet but PADDING, APPLICATION, SEEKTABLE,
- * CUESHEET and PICTURE may follow. The last metadata block must have its
- * first bit set to 1. Since liboggz does not know whether you will supply
- * more metadata blocks you must tell it if this is the last (and only
- * block) via FLAC_final_metadata_block.
- * \n Additionally FLAC metadata blocks are limited to 16MB minus 1 byte of
- * content, this function will refuse to produce longer comment packets
- * for FLAC.
+ * \note FLAC streams may contain multiple metadata blocks of different types.
+ * When encapsulated in Ogg the first of these must be a Vorbis comment packet
+ * but PADDING, APPLICATION, SEEKTABLE, CUESHEET and PICTURE may follow.
+ * The last metadata block must have its first bit set to 1. Since liboggz does
+ * not know whether you will supply more metadata blocks you must tell it if
+ * this is the last (or only) metadata block by setting
+ * FLAC_final_metadata_block to 1.
+ * \n As FLAC metadata blocks are limited in size to 16MB minus 1 byte, this
+ * function will refuse to produce longer comment packets for FLAC.
  * \n See http://flac.sourceforge.net/format.html for more details.
  */
 ogg_packet *