Cleanup pass on the vorbisenc documentation.

svn path=/trunk/vorbis/; revision=16757

Author: rillian

doc/vorbisenc/vorbis_analysis.html

@@ -22,7 +22,7 @@ <h1>vorbis_analysis</h1>
 dispatches the block to the forward transform provided by that mode.
 </p>
 <p>When using a basic encoding mode, with no bitrate management,
-an ogg_packet pointer can be given, and an the coded block is returned
+an ogg_packet pointer can be given, and the coded block is returned
 directly through that structure and can be placed in the output stream.
 </p>
 <p>Otherwise, NULL should be passed for the ogg_packet pointer. In
@@ -46,9 +46,9 @@ <h3>Parameters</h3>
 <dt><i>vb</i></dt>
 <dd>Pointer to the vorbis_block to be encoded.</dd>
 <dt><i>op</i></dt>
-<dd>Optional pointer to an ogg_packet. This should normally NULL,
-and the final output obtained by passing <i>vb</i> though the
-vorbis_bitrate_*() interface to perform any further refinement.
+<dd>Optional pointer to an ogg_packet. This is normally NULL,
+and the final output is obtained by passing <i>vb</i> though the
+vorbis_bitrate_*() interface to perform further refinement.
 However, when not using a bitrate managed encoding mode, it
 is possible to skip that step by providing an ogg_packet pointer
 here, obtaining the compressed data directly.</dd>

doc/vorbisenc/vorbis_analysis_blockout.html

@@ -17,9 +17,9 @@ <h1>vorbis_analysis_blockout</h1>
 
 <p><i>declared in "vorbis/codec.h";</i></p>
 
-<p>This fuction examines the available encoder and tries to break it
-into appropriate sized blocks. It should be called in a loop after
-adding new data with vorbis_analysis_buffer()/vorbis_analysis_wrote()
+<p>This fuction examines the available uncompressed data and tries to
+break it into appropriate sized blocks. It should be called in a loop
+after adding new data with vorbis_analysis_buffer()/vorbis_analysis_wrote()
 until it returns zero (need more data) or an negative value (error).
 </p>
 <p>
@@ -42,7 +42,7 @@ <h3>Parameters</h3>
 <dt><i>v</i></dt>
 <dd>Pointer to the vorbis_dsp_state representing the encoder.</dd>
 <dt><i>vb</i></dt>
-<dd>Pointer to a previously initialize vorbis_block object to store the
+<dd>Pointer to a previously initialized vorbis_block object to hold the
 returned data.
 </dl>
 

doc/vorbisenc/vorbis_analysis_buffer.html

@@ -47,7 +47,7 @@ <h3>Parameters</h3>
 <dt><i>v</i></dt>
 <dd>Pointer to the vorbis_dsp_state representing the encoder.</dd>
 <dt><i>vals</i></dt>
-<dd>Number of samples to provide in the request buffer.</dd>
+<dd>Number of samples to provide space for in the returned buffer. 1024 is a reasonable choice.</dd>
 </dl>
 
 

doc/vorbisenc/vorbis_analysis_headerout.html

@@ -18,7 +18,7 @@ <h1>vorbis_analysis_headerout</h1>
 <p><i>declared in "vorbis/codec.h";</i></p>
 
 <p>This function creates and returns the three header packets needed
-to configure a decoder to accept subsequent data. I should be called
+to configure a decoder to accept compressed data. I should be called
 after all encoder initialization and configuration is complete. The
 output packets should be placed in order at the start of the compressed
 vorbis stream, prior to the first data packet.

doc/vorbisenc/vorbis_analysis_init.html

@@ -37,7 +37,7 @@ <h3>Parameters</h3>
 <dt><i>v</i</dt>
 <dd>Pointer to the vorbis_dsp_state structure to be initialized for encoding.</dd>
 <dt><i>vi</i></dt>
-<dd>File pointer to an initialized <a href="vorbis_info.html">vorbis_info</a> struct.</dd>
+<dd>Pointer to an initialized <a href="vorbis_info.html">vorbis_info</a> struct describing the encoder configuration.</dd>
 </dl>
 
 

doc/vorbisenc/vorbis_analysis_wrote.html

@@ -22,6 +22,11 @@ <h1>vorbis_analysis_wrote</h1>
 vorbis_analysis_buffer().
 </p>
 
+<p>
+Call with the <i>vals</i> parameter set to zero to signal the end
+of the input data.
+</p>
+
 <table border=0 color=black cellspacing=0 cellpadding=7>
 <tr bgcolor=#cccccc>
 	<td>
@@ -38,7 +43,9 @@ <h3>Parameters</h3>
 <dd>Pointer to the vorbis_dsp_state representing the encoder.</dd>
 <dt><i>vals</i></dt>
 <dd>Number of samples successfully written. This must be less than
-or equal to the value passed to vorbis_analysis_buffer().</dd>
+or equal to the value passed to vorbis_analysis_buffer(). A value
+of zero means all input data has been provided and the compressed
+stream should be finalized.</dd>
 </dl>
 
 

doc/vorbisenc/vorbis_bitrate_addblock.html

@@ -18,9 +18,9 @@ <h1>vorbis_bitrate_addblock</h1>
 <p><i>declared in "vorbis/codec.h";</i></p>
 
 <p>This fuction submits a transformed block to the bitrate management
-engine for final encoding. Packets are submitted and, depending on the
-encoding mode, buffered and the packet boundaries adjusted and padded
-to meet the target bitrate.</p>
+engine for final encoding. Packets are buffered and the packet boundaries
+adjusted and padded to meet the target bitrate, if any.</p>
+
 <p>After calling vorbis_bitrate_addblock(), the passed vorbis_block
 structure can be reused in another call to vorbis_analysis_blockout().
 Call vorbis_bitrate_flushpacket() to obtain the final compressed data.
@@ -38,7 +38,7 @@ <h1>vorbis_bitrate_addblock</h1>
 
 <h3>Parameters</h3>
 <dl>
-<dt><i>v</i></dt>
+<dt><i>vb</i></dt>
 <dd>Pointer to the vorbis_block to be submitted.</dd>
 </dl>
 

doc/vorbisenc/vorbis_bitrate_flushpacket.html

@@ -17,9 +17,9 @@ <h1>vorbis_bitrate_flushpacket</h1>
 
 <p><i>declared in "vorbis/codec.h";</i></p>
 
-<p>This function returns the next available packet from the bitrate
-management engine. It should be called in a loop after any calls to
-vorbis_bitrate_addblock() until it returns either 0 (more data needed)
+<p>This function returns the next available completed packet from the
+bitrate management engine. It should be called in a loop after any call
+to vorbis_bitrate_addblock() until it returns either 0 (more data needed)
 or a negative value (error).
 </p>
 

doc/vorbisenc/vorbis_block_init.html

@@ -17,9 +17,9 @@ <h1>vorbis_block_init</h1>
 
 <p><i>declared in "vorbis/codec.h";</i></p>
 
-<p>This function allocates and initializes internal state associated
-with dividing the input into blocks for further analysis, stored inside
-a vorbis_block structure.
+<p>This function initializes a vorbis_block structure and allocates its
+internal storage. A vorbis_block is used to represent a particular block
+of input audio which can be analyzed and coded as a unit.
 </p>
 
 <table border=0 color=black cellspacing=0 cellpadding=7>
@@ -36,7 +36,7 @@ <h3>Parameters</h3>
 <dl>
 <dt><i>v</i</dt>
 <dd>Pointer to an initialized vorbis_dsp_state with which to associate the new block.</dd>
-<dt><i>vi</i></dt>
+<dt><i>vb</i></dt>
 <dd>Pointer to a vorbis_block struct to be initialized.</dd>
 </dl>
 

doc/vorbisenc/vorbis_encode_ctl.html

@@ -46,7 +46,7 @@ <h1>vorbis_encode_ctl</h1>
 <h3>Parameters</h3>
 <dl>
 <dt><i>vi</i></dt>
-<dd>File pointer to an initialized <a href="vorbis_info.html">vorbis_info</a> struct.</dd><p>
+<dd>Pointer to an initialized <a href="vorbis_info.html">vorbis_info</a> struct.</dd><p>
 <dt><i>request</i></dt>
 <dd>Specifies the desired action; possible request fields are detailed below.</dd><p>
 <dt><i>arg</i></dt>