minor comments

include/FLAC/stream_decoder.h

@@ -334,7 +334,8 @@ typedef struct {
  *                  to the callback, it contains the maximum number
  *                  of bytes that may be stored in \a buffer.  The
  *                  callee must set it to the actual number of bytes
- *                  stored before returning.
+ *                  stored (0 in case of error or end-of-stream) before
+ *                  returning.
  * \param  client_data  The callee's client data set through
  *                      FLAC__stream_decoder_set_client_data().
  * \retval FLAC__StreamDecoderReadStatus

src/libOggFLAC/ogg_encoder_aspect.c

@@ -95,6 +95,7 @@ FLAC__StreamEncoderWriteStatus OggFLAC__ogg_encoder_aspect_write_callback_wrappe
 		return FLAC__STREAM_ENCODER_WRITE_STATUS_FATAL_ERROR;
 
 #ifdef FLAC__ONE_FLAC_FRAME_PER_OGG_PAGE
+	/* WATCHOUT: a FLAC frame may not be able to fit in a single Ogg page */
 	while(ogg_stream_flush(&aspect->stream_state, &aspect->page) != 0) {
 		if(write_callback(encoder, aspect->page.header, aspect->page.header_len, 0, current_frame, client_data) != FLAC__STREAM_ENCODER_WRITE_STATUS_OK)
 			return FLAC__STREAM_ENCODER_WRITE_STATUS_FATAL_ERROR;