Fix up comments a bit to start being more uniform.

Tokstyle (check-cimple) will start enforcing comment formats at some
point. It will not support arbitrary stuff in comments, and will parse
them. The result can then be semantically analysed.

7 files changed, 27 insertions, 24 deletions

diff --git a/toxav/audio.c b/toxav/audio.c
index d4618aaf..b936f7a4 100644
--- a/toxav/audio.c
+++ b/toxav/audio.c
@@ -378,7 +378,7 @@ OpusEncoder *create_audio_encoder(const Logger *log, int32_t bit_rate, int32_t s
      * controlling the rate by adjusting the output buffer size.
      *
      * Parameters:
-     *   [in]    x   opus_int32: bitrate in bits per second.
+     *   `[in]`    `x`   `opus_int32`: bitrate in bits per second.
      */
     status = opus_encoder_ctl(rc, OPUS_SET_BITRATE(bit_rate));
 
@@ -393,7 +393,7 @@ OpusEncoder *create_audio_encoder(const Logger *log, int32_t bit_rate, int32_t s
      * Note:
      *   This is only applicable to the LPC layer
      * Parameters:
-     *   [in]    x   int: FEC flag, 0 (disabled) is default
+     *   `[in]`    `x`   `int`: FEC flag, 0 (disabled) is default
      */
     /* Enable in-band forward error correction in codec */
     status = opus_encoder_ctl(rc, OPUS_SET_INBAND_FEC(1));
@@ -410,7 +410,7 @@ OpusEncoder *create_audio_encoder(const Logger *log, int32_t bit_rate, int32_t s
      * the encoder at the expense of quality at a given bitrate in the lossless case,
      * but greater quality under loss.
      * Parameters:
-     *     [in]    x   int: Loss percentage in the range 0-100, inclusive.
+     *     `[in]`    `x`   `int`: Loss percentage in the range 0-100, inclusive.
      */
     /* Make codec resistant to up to 10% packet loss
      * NOTE This could also be adjusted on the fly, rather than hard-coded,
@@ -431,7 +431,7 @@ OpusEncoder *create_audio_encoder(const Logger *log, int32_t bit_rate, int32_t s
      * The default value is 10.
      *
      * Parameters:
-     *   [in]    x   int: 0-10, inclusive
+     *   `[in]`    `x`   `int`: 0-10, inclusive
      */
     /* Set algorithm to the highest complexity, maximizing compression */
     status = opus_encoder_ctl(rc, OPUS_SET_COMPLEXITY(AUDIO_OPUS_COMPLEXITY));
diff --git a/toxav/msi.c b/toxav/msi.c
index 84a18f36..69046079 100644
--- a/toxav/msi.c
+++ b/toxav/msi.c
@@ -21,7 +21,7 @@
 /**
  * Protocol:
  *
- * |id [1 byte]| |size [1 byte]| |data [$size bytes]| |...{repeat}| |0 {end byte}|
+ * `|id [1 byte]| |size [1 byte]| |data [$size bytes]| |...{repeat}| |0 {end byte}|`
  */
 
 typedef enum MSIHeaderID {
diff --git a/toxav/msi.h b/toxav/msi.h
index e50171e5..5809228d 100644
--- a/toxav/msi.h
+++ b/toxav/msi.h
@@ -121,7 +121,7 @@ void msi_register_callback(MSISession *session, msi_action_cb *callback, MSICall
  */
 int msi_invite(MSISession *session, MSICall **call, uint32_t friend_number, uint8_t capabilities);
 /**
- * Hangup call. NOTE: 'call' will be freed
+ * Hangup call. NOTE: `call` will be freed
  */
 int msi_hangup(MSICall *call);
 /**
diff --git a/toxav/rtp.c b/toxav/rtp.c
index 35898b68..aed9523b 100644
--- a/toxav/rtp.c
+++ b/toxav/rtp.c
@@ -319,9 +319,11 @@ static void update_bwc_values(const Logger *log, RTPSession *session, const stru
  * find out and handle it appropriately.
  *
  * @param session The current RTP session with:
+ *   <code>
  *   session->mcb == vc_queue_message() // this function is called from here
  *   session->mp == struct RTPMessage *
  *   session->cs == call->video.second // == VCSession created by vc_new() call
+ *   </code>
  * @param header The RTP header deserialised from the packet.
  * @param incoming_data The packet data *not* header, i.e. this is the actual
  *   payload.
diff --git a/toxav/rtp.h b/toxav/rtp.h
index b6217d95..46cd6b86 100644
--- a/toxav/rtp.h
+++ b/toxav/rtp.h
@@ -122,7 +122,7 @@ struct RTPMessage {
 struct RTPWorkBuffer {
     /**
      * Whether this slot contains a key frame. This is true iff
-     * buf->header.flags & RTP_KEY_FRAME.
+     * `buf->header.flags & RTP_KEY_FRAME`.
      */
     bool is_keyframe;
     /**
diff --git a/toxav/toxav_old.c b/toxav/toxav_old.c
index 9ecc7969..e5cfbadc 100644
--- a/toxav/toxav_old.c
+++ b/toxav/toxav_old.c
@@ -17,9 +17,9 @@
  * return -1 on failure.
  *
  * Audio data callback format:
- *   audio_callback(Tox *tox, int groupnumber, int peernumber, const int16_t *pcm, unsigned int samples, uint8_t channels, unsigned int sample_rate, void *userdata)
+ *   `audio_callback(Tox *tox, int groupnumber, int peernumber, const int16_t *pcm, unsigned int samples, uint8_t channels, unsigned int sample_rate, void *userdata)`
  *
- * Note that total size of pcm in bytes is equal to (samples * channels * sizeof(int16_t)).
+ * Note that total size of pcm in bytes is equal to `(samples * channels * sizeof(int16_t))`.
  */
 int toxav_add_av_groupchat(Tox *tox, audio_data_cb *audio_callback, void *userdata)
 {
@@ -33,10 +33,10 @@ int toxav_add_av_groupchat(Tox *tox, audio_data_cb *audio_callback, void *userda
  * returns group number on success
  * returns -1 on failure.
  *
- * Audio data callback format (same as the one for toxav_add_av_groupchat()):
- *   audio_callback(Tox *tox, int groupnumber, int peernumber, const int16_t *pcm, unsigned int samples, uint8_t channels, unsigned int sample_rate, void *userdata)
+ * Audio data callback format (same as the one for `toxav_add_av_groupchat()`):
+ *   `audio_callback(Tox *tox, int groupnumber, int peernumber, const int16_t *pcm, unsigned int samples, uint8_t channels, unsigned int sample_rate, void *userdata)`
  *
- * Note that total size of pcm in bytes is equal to (samples * channels * sizeof(int16_t)).
+ * Note that total size of pcm in bytes is equal to `(samples * channels * sizeof(int16_t))`.
  */
 int toxav_join_av_groupchat(Tox *tox, uint32_t friendnumber, const uint8_t *data, uint16_t length,
                             audio_data_cb *audio_callback, void *userdata)
@@ -51,9 +51,9 @@ int toxav_join_av_groupchat(Tox *tox, uint32_t friendnumber, const uint8_t *data
  * return 0 on success.
  * return -1 on failure.
  *
- * Note that total size of pcm in bytes is equal to (samples * channels * sizeof(int16_t)).
+ * Note that total size of pcm in bytes is equal to `(samples * channels * sizeof(int16_t))`.
  *
- * Valid number of samples are ((sample rate) * (audio length (Valid ones are: 2.5, 5, 10, 20, 40 or 60 ms)) / 1000)
+ * Valid number of samples are `((sample rate) * (audio length) / 1000)` (Valid values for audio length: 2.5, 5, 10, 20, 40 or 60 ms)
  * Valid number of channels are 1 or 2.
  * Valid sample rates are 8000, 12000, 16000, 24000, or 48000.
  *
@@ -81,9 +81,9 @@ int toxav_group_send_audio(Tox *tox, uint32_t groupnumber, const int16_t *pcm, u
  * return -1 on failure.
  *
  * Audio data callback format (same as the one for toxav_add_av_groupchat()):
- *   audio_callback(Tox *tox, uint32_t groupnumber, uint32_t peernumber, const int16_t *pcm, unsigned int samples, uint8_t channels, uint32_t sample_rate, void *userdata)
+ *   `audio_callback(Tox *tox, uint32_t groupnumber, uint32_t peernumber, const int16_t *pcm, unsigned int samples, uint8_t channels, uint32_t sample_rate, void *userdata)`
  *
- * Note that total size of pcm in bytes is equal to (samples * channels * sizeof(int16_t)).
+ * Note that total size of pcm in bytes is equal to `(samples * channels * sizeof(int16_t))`.
  */
 int toxav_groupchat_enable_av(Tox *tox, uint32_t groupnumber, audio_data_cb *audio_callback, void *userdata)
 {
diff --git a/toxav/video.c b/toxav/video.c
index c6206bbf..7855f142 100644
--- a/toxav/video.c
+++ b/toxav/video.c
@@ -241,15 +241,16 @@ VCSession *vc_new(Mono_Time *mono_time, const Logger *log, ToxAV *av, uint32_t f
     control function to set noise sensitivity
       0: off, 1: OnYOnly, 2: OnYUV, 3: OnYUVAggressive, 4: Adaptive
     */
-    /*
-      rc = vpx_codec_control(vc->encoder, VP8E_SET_NOISE_SENSITIVITY, 2);
+#if 0
+    rc = vpx_codec_control(vc->encoder, VP8E_SET_NOISE_SENSITIVITY, 2);
 
-      if (rc != VPX_CODEC_OK) {
-          LOGGER_ERROR(log, "Failed to set encoder control setting: %s", vpx_codec_err_to_string(rc));
-          vpx_codec_destroy(vc->encoder);
-          goto BASE_CLEANUP_1;
-      }
-     */
+    if (rc != VPX_CODEC_OK) {
+        LOGGER_ERROR(log, "Failed to set encoder control setting: %s", vpx_codec_err_to_string(rc));
+        vpx_codec_destroy(vc->encoder);
+        goto BASE_CLEANUP_1;
+    }
+
+#endif
     vc->linfts = current_time_monotonic(mono_time);
     vc->lcfd = 60;
     vc->vcb = cb;