Improve documentation of ogg_stream_flush_fill and related calls.

git-svn-id: http://svn.xiph.org/trunk/ogg@18053 0101bb08-14d6-0310-b084-bc0e0c8e3800

5 files changed, 18 insertions, 7 deletions

diff --git a/doc/libogg/encoding.html b/doc/libogg/encoding.html
index 1fa3c0a..d97cfbd 100644
--- a/doc/libogg/encoding.html
+++ b/doc/libogg/encoding.html
@@ -53,6 +53,10 @@ All the <b>libogg</b> specific functions are declared in "ogg/ogg.h".
 <td><a href="ogg_stream_flush.html">ogg_stream_flush</a></td>
 	<td>Forces any remaining packets in the stream to be returned as a page of any size.<td>
 </tr>
+<tr valign=top>
+<td><a href="ogg_stream_flush_fill.html">ogg_stream_flush_fill</a></td>
+	<td>Similar to ogg_stream_flush(), but specifies a page spill threshold in bytes.<td>
+</tr>
 </table>
 
 <br><br>
diff --git a/doc/libogg/ogg_stream_flush.html b/doc/libogg/ogg_stream_flush.html
index ddc747b..31f2171 100644
--- a/doc/libogg/ogg_stream_flush.html
+++ b/doc/libogg/ogg_stream_flush.html
@@ -18,8 +18,8 @@
 <p><i>declared in "ogg/ogg.h";</i></p>
 
 <p>This function checks for remaining packets inside the stream and forces remaining packets into a page, regardless of the size of the page.
-<p>This should only be used when you want to flush an undersized page from the middle of the stream.  Otherwise, <a href="ogg_stream_pageout.html">ogg_stream_pageout</a> or <a href="ogg_stream_pageout_fill.html">ogg_stream_pageout_fill</a>should always be used.  
-<p>This function can be used to verify that all packets have been flushed.  If the return value is 0, all packets have been placed into a page.
+<p>This should only be used when you want to flush an undersized page from the middle of the stream.  Otherwise, <a href="ogg_stream_pageout.html">ogg_stream_pageout</a> or <a href="ogg_stream_pageout_fill.html">ogg_stream_pageout_fill</a>should always be used.
+<p>This function can also be used to verify that all packets have been flushed.  If the return value is 0, all packets have been placed into a page. Like <a href="ogg_stream_pageout.html">ogg_stream_pageout</a>, it should generally be called in a loop until available packet data has been flushes, since even a single packet may span multiple pages.
 
 <br><br>
 <table border=0 color=black cellspacing=0 cellpadding=7>
diff --git a/doc/libogg/ogg_stream_flush_fill.html b/doc/libogg/ogg_stream_flush_fill.html
index 8fbc8d2..d455a6b 100644
--- a/doc/libogg/ogg_stream_flush_fill.html
+++ b/doc/libogg/ogg_stream_flush_fill.html
@@ -17,9 +17,14 @@
 
 <p><i>declared in "ogg/ogg.h";</i></p>
 
-<p>This function checks for remaining packets inside the stream and forces remaining packets into a page, regardless of the size of the page.
-<p>This should only be used when you want to flush an undersized page from the middle of the stream.  Otherwise, <a href="ogg_stream_pageout.html">ogg_stream_pageout</a> or <a href="ogg_stream_pageout_fill.html">ogg_stream_pageout_fill</a>should always be used.  
-<p>This function can be used to verify that all packets have been flushed.  If the return value is 0, all packets have been placed into a page.
+<p>This function flushes available packets into pages, similar to
+<a href="ogg_stream_flush.html">ogg_stream_flush()</a>, but
+allows applications to explicitly request a specific page spill
+size.</p>
+
+<p>This function checks for remaining packets inside the stream and forces remaining packets into pages of approximately the requested size.
+This should be used when you want to flush all remaining data from a stream. <a href="ogg_stream_flush.html">ogg_stream_flush</a> may be used instead if a particular page size isn't important. 
+<p>This function can be used to verify that all packets have been flushed.  If the return value is 0, all packets have been placed into a page. Generally speaking, it should be called in a loop until all packets are flushed, since even a single packet may span multiple pages.
 
 <br><br>
 <table border=0 color=black cellspacing=0 cellpadding=7>
diff --git a/doc/libogg/ogg_stream_pageout_fill.html b/doc/libogg/ogg_stream_pageout_fill.html
index 13bd6ab..d005999 100644
--- a/doc/libogg/ogg_stream_pageout_fill.html
+++ b/doc/libogg/ogg_stream_pageout_fill.html
@@ -33,8 +33,9 @@ are no more pages ready for output.</p>
 been accumulated and accumulated packet data meets or exceeds the
 specified number of bytes, <b>and/or</b> when the accumulated packet
 data meets/exceeds the maximum page size regardless of accumulated
-packet
-count. Call <a href="ogg_stream_flush.html">ogg_stream_flush()</a> if
+packet count.
+Call <a href="ogg_stream_flush.html">ogg_stream_flush()</a> or
+<a href="ogg_stream_flush_fill.html">ogg_stream_flush_fill()</a> if
 immediate page generation is desired regardless of accumulated data.</p>
 
 <br><br>
diff --git a/doc/libogg/reference.html b/doc/libogg/reference.html
index 45cdf97..d006e61 100644
--- a/doc/libogg/reference.html
+++ b/doc/libogg/reference.html
@@ -62,6 +62,7 @@
 <a href="ogg_stream_pageout.html">ogg_stream_pageout()</a><br>
 <a href="ogg_stream_pageout_fill.html">ogg_stream_pageout_fill()</a><br>
 <a href="ogg_stream_flush.html">ogg_stream_flush()</a><br>
+<a href="ogg_stream_flush_fill.html">ogg_stream_flush_fill()</a><br>
 <br>
 <b>General</b><br>
 <a href="ogg_stream_init.html">ogg_stream_init()</a><br>