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.

2 files changed, 63 insertions, 5 deletions

diff --git a/include/opus.h b/include/opus.h
index c552fc27..df2103f7 100644
--- a/include/opus.h
+++ b/include/opus.h
@@ -261,6 +261,9 @@ OPUS_EXPORT int opus_encode_float(
 OPUS_EXPORT void opus_encoder_destroy(OpusEncoder *st);
 
 /** Perform a CTL function on an Opus encoder.
+  *
+  * Generally the request and subsequent arguments are generated
+  * by a convenience macro.
   * @see encoderctls
   */
 OPUS_EXPORT int opus_encoder_ctl(OpusEncoder *st, int request, ...);
@@ -398,7 +401,10 @@ OPUS_EXPORT int opus_decode_float(
 );
 
 /** Perform a CTL function on an Opus decoder.
-  * @see decoderctls
+  *
+  * Generally the request and subsequent arguments are generated
+  * by a convenience macro.
+  * @see genericctls
   */
 OPUS_EXPORT int opus_decoder_ctl(OpusDecoder *st, int request, ...);
 
@@ -455,7 +461,7 @@ OPUS_EXPORT int opus_packet_get_samples_per_frame(const unsigned char *data, opu
   */
 OPUS_EXPORT int opus_packet_get_nb_channels(const unsigned char *data);
 
-/** Gets the number of frame in an Opus packet.
+/** Gets the number of frames in an Opus packet.
   * @param [in] packet <tt>char*</tt>: Opus packet
   * @param [in] len <tt>int</tt>: Length of packet
   * @returns Number of frames
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 */