diff --git a/include/opus.h b/include/opus.h
index c552fc2705131966e8e41a547b9ad9dcc0af559e..df2103f79eae72f9a9fe57b364f83329b600770c 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 50ff16c117bf49854b935fadfe5b03cac472e084..883f9d120a2f4ade65c466e32acfbe8d161f82a3 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 */