Misc documentation fixes (no code change)

We use macros to encapsulate the appropriate type and size
information for the different CTL requests, but the macros
still need to be used with the _ctl() function call and an
encoder or decoder instance structure. As such, just listing
the macro defines is confusing. Adding some examples outside
the OpusEncoder overview page should help with this.

Also document that OPUS_SET_APPLICATION can take
OPUS_APPLICATION_RESTRICTED_LOWDELAY.

1 files changed, 55 insertions, 3 deletions

diff --git a/include/opus_defines.h b/include/opus_defines.h
index 50ff16c1..883f9d12 100644
--- a/include/opus_defines.h
+++ b/include/opus_defines.h
@@ -113,7 +113,7 @@ extern "C" {
 /** @endcond */
 
 /** @defgroup ctlvalues Pre-defined values for CTL interface
-  * @see genericctls,encoderctls
+  * @see genericctls, encoderctls
   * @{
   */
 /* Values for the various encoder CTLs */
@@ -142,7 +142,26 @@ extern "C" {
 
 
 /** @defgroup encoderctls Encoder related CTLs
-  * @see genericctls,opusencoder
+  *
+  * These are convenience macros for use with the \c opus_encode_ctl
+  * interface. They are used to generate the appropriate series of
+  * arguments for that call, passing the correct type, size and so
+  * on as expected for each particular request.
+  *
+  * Some usage examples:
+  *
+  * @code
+  * int ret;
+  * ret = opus_encoder_ctl(enc_ctx, OPUS_SET_BANDWIDTH(OPUS_AUTO));
+  * if (ret != OPUS_OK) return ret;
+  *
+  * int rate;
+  * opus_encoder_ctl(enc_ctx, OPUS_GET_BANDWIDTH(&rate));
+  *
+  * opus_encoder_ctl(enc_ctx, OPUS_RESET_STATE);
+  * @endcode
+  *
+  * @see genericctls, opusencoder
   * @{
   */
 
@@ -263,6 +282,8 @@ extern "C" {
   * The supported values are:
   *  - OPUS_APPLICATION_VOIP Process signal for improved speech intelligibility
   *  - OPUS_APPLICATION_AUDIO Favor faithfulness to the original input
+  *  - OPUS_APPLICATION_RESTRICTED_LOWDELAY Configure the minimum possible coding delay
+  *
   * @param[in] x <tt>int</tt>:     Application value
   * @hideinitializer */
 #define OPUS_SET_APPLICATION(x) OPUS_SET_APPLICATION_REQUEST, __opus_check_int(x)
@@ -327,7 +348,36 @@ extern "C" {
 /**@}*/
 
 /** @defgroup genericctls Generic CTLs
-  * @see opus_encoder_ctl,opusencoder,opusdecoder
+  *
+  * These macros are used with the \c opus_decoder_ctl and
+  * \c opus_encoder_ctl calls to generate a particular
+  * request.
+  *
+  * When called on an \c OpusDecoder they apply to that
+  * particular decoder instance. When called on an
+  * \c OpusEncoder they apply to the corresponding setting
+  * on that encoder instance, if present.
+  *
+  * Some usage examples:
+  *
+  * @code
+  * int ret;
+  * opus_int32 pitch;
+  * ret = opus_decoder_ctl(dec_ctx, OPUS_GET_PITCH(&pitch));
+  * if (ret == OPUS_OK) return ret;
+  *
+  * opus_encoder_ctl(enc_ctx, OPUS_RESET_STATE);
+  * opus_decoder_ctl(dec_ctx, OPUS_RESET_STATE);
+  *
+  * opus_int32 enc_bw, dec_bw;
+  * opus_encoder_ctl(enc_ctx, OPUS_GET_BANDWIDTH(&enc_bw));
+  * opus_decoder_ctl(dec_ctx, OPUS_GET_BANDWIDTH(&dec_bw));
+  * if (enc_bw != dec_bw) {
+  *   printf("packet bandwidth mismatch!\n");
+  * }
+  * @endcode
+  *
+  * @see opusencoder, opus_decoder_ctl, opus_encoder_ctl
   * @{
   */
 
@@ -353,6 +403,8 @@ extern "C" {
   * e.g. time stretching/shortening. If the last frame was not voiced, or if the
   * pitch was not coded in the frame, then zero is returned.
   *
+  * This CTL is only implemented for decoder instances.
+  *
   * @param[out] x <tt>opus_int32*</tt>: pitch period at 48 kHz (or 0 if not available)
   *
   * @hideinitializer */