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.
TokTok · Mar 14, 2020 · cb22b3d · cb22b3d
1 parent 11ad547
commit cb22b3d
Show file tree

Hide file tree

Showing 23 changed files with 109 additions and 144 deletions.
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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;

diff --git a/toxcore/DHT.c b/toxcore/DHT.c
@@ -610,7 +610,7 @@ int unpack_nodes(Node_format *nodes, uint16_t max_num_nodes, uint16_t *processed
     return num;
 }
 
-/* Find index of ##type with public_key equal to pk.
+/* Find index in an array with public_key equal to pk.
  *
  *  return index or UINT32_MAX if not found.
  */
@@ -1112,7 +1112,7 @@ static bool is_pk_in_close_list(DHT *dht, const uint8_t *public_key, IP_Port ip_
 }
 
 /* Check if the node obtained with a get_nodes with public_key should be pinged.
- * NOTE: for best results call it after addto_lists;
+ * NOTE: for best results call it after addto_lists.
  *
  * return false if the node should not be pinged.
  * return true if it should.

diff --git a/toxcore/DHT.h b/toxcore/DHT.h
@@ -271,8 +271,6 @@ int dht_delfriend(DHT *dht, const uint8_t *public_key, uint16_t lock_count);
  *  ip must be 4 bytes long.
  *  port must be 2 bytes long.
  *
- * int dht_getfriendip(DHT *dht, uint8_t *public_key, IP_Port *ip_port);
- *
  *  return -1, -- if public_key does NOT refer to a friend
  *  return  0, -- if public_key refers to a friend and we failed to find the friend (yet)
  *  return  1, ip if public_key refers to a friend and we found him

diff --git a/toxcore/LAN_discovery.c b/toxcore/LAN_discovery.c
@@ -57,8 +57,8 @@ static void fetch_broadcast_info(uint16_t port)
         }
     }
 
-    /* We copy these to the static variables broadcast_* only at the end of fetch_broadcast_info().
-     * The intention is to ensure that even if multiple threads enter fetch_broadcast_info() concurrently, only valid
+    /* We copy these to the static variables `broadcast_*` only at the end of `fetch_broadcast_info()`.
+     * The intention is to ensure that even if multiple threads enter `fetch_broadcast_info()` concurrently, only valid
      * interfaces will be set to be broadcast to.
      * */
     int count = 0;
@@ -123,7 +123,7 @@ static void fetch_broadcast_info(uint16_t port)
 static void fetch_broadcast_info(uint16_t port)
 {
     /* Not sure how many platforms this will run on,
-     * so it's wrapped in __linux for now.
+     * so it's wrapped in `__linux__` for now.
      * Definitely won't work like this on Windows...
      */
     broadcast_count = 0;
@@ -146,15 +146,15 @@ static void fetch_broadcast_info(uint16_t port)
         return;
     }
 
-    /* We copy these to the static variables broadcast_* only at the end of fetch_broadcast_info().
-     * The intention is to ensure that even if multiple threads enter fetch_broadcast_info() concurrently, only valid
+    /* We copy these to the static variables `broadcast_*` only at the end of `fetch_broadcast_info()`.
+     * The intention is to ensure that even if multiple threads enter `fetch_broadcast_info()` concurrently, only valid
      * interfaces will be set to be broadcast to.
      * */
     int count = 0;
     IP_Port ip_ports[MAX_INTERFACES];
 
-    /* ifc.ifc_len is set by the ioctl() to the actual length used;
-     * on usage of the complete array the call should be repeated with
+    /* `ifc.ifc_len` is set by the `ioctl()` to the actual length used.
+     * On usage of the complete array the call should be repeated with
      * a larger array, not done (640kB and 16 interfaces shall be
      * enough, for everybody!)
      */
@@ -239,8 +239,8 @@ static IP broadcast_ip(Family family_socket, Family family_broadcast)
     if (net_family_is_ipv6(family_socket)) {
         if (net_family_is_ipv6(family_broadcast)) {
             ip.family = net_family_ipv6;
-            /* FF02::1 is - according to RFC 4291 - multicast all-nodes link-local */
-            /* FE80::*: MUST be exact, for that we would need to look over all
+            /* `FF02::1` is - according to RFC 4291 - multicast all-nodes link-local */
+            /* `FE80::*:` MUST be exact, for that we would need to look over all
              * interfaces and check in which status they are */
             ip.ip.v6.uint8[ 0] = 0xFF;
             ip.ip.v6.uint8[ 1] = 0x02;
@@ -328,8 +328,8 @@ bool ip_is_lan(IP ip)
     }
 
     if (net_family_is_ipv6(ip.family)) {
-        /* autogenerated for each interface: FE80::* (up to FEBF::*)
-           FF02::1 is - according to RFC 4291 - multicast all-nodes link-local */
+        /* autogenerated for each interface: `FE80::*` (up to `FEBF::*`)
+           `FF02::1` is - according to RFC 4291 - multicast all-nodes link-local */
         if (((ip.ip.v6.uint8[0] == 0xFF) && (ip.ip.v6.uint8[1] < 3) && (ip.ip.v6.uint8[15] == 1)) ||
                 ((ip.ip.v6.uint8[0] == 0xFE) && ((ip.ip.v6.uint8[1] & 0xC0) == 0x80))) {
             return true;

diff --git a/toxcore/Messenger.c b/toxcore/Messenger.c
@@ -125,7 +125,7 @@ static uint16_t address_checksum(const uint8_t *address, uint32_t len)
     return check;
 }
 
-/* Format: [real_pk (32 bytes)][nospam number (4 bytes)][checksum (2 bytes)]
+/* Format: `[real_pk (32 bytes)][nospam number (4 bytes)][checksum (2 bytes)]`
  *
  *  return FRIEND_ADDRESS_SIZE byte address to give to others.
  */
@@ -971,12 +971,10 @@ static int write_cryptpacket_id(const Messenger *m, int32_t friendnumber, uint8_
                              m->friendlist[friendnumber].friendcon_id), packet, length + 1, congestion_control) != -1;
 }
 
-/**********CONFERENCES************/
+/** CONFERENCES */
 
 
 /* Set the callback for conference invites.
- *
- *  Function(Messenger *m, uint32_t friendnumber, uint8_t *data, uint16_t length, void *userdata)
  */
 void m_callback_conference_invite(Messenger *m, m_conference_invite_cb *function)
 {
@@ -994,42 +992,31 @@ int send_conference_invite_packet(const Messenger *m, int32_t friendnumber, cons
     return write_cryptpacket_id(m, friendnumber, PACKET_ID_INVITE_CONFERENCE, data, length, 0);
 }
 
-/****************FILE SENDING*****************/
+/** FILE SENDING */
 
 
 /* Set the callback for file send requests.
- *
- *  Function(Tox *tox, uint32_t friendnumber, uint32_t filenumber, uint32_t filetype, uint64_t filesize, uint8_t *filename, size_t filename_length, void *userdata)
  */
 void callback_file_sendrequest(Messenger *m, m_file_recv_cb *function)
 {
     m->file_sendrequest = function;
 }
 
 /* Set the callback for file control requests.
- *
- *  Function(Tox *tox, uint32_t friendnumber, uint32_t filenumber, unsigned int control_type, void *userdata)
- *
  */
 void callback_file_control(Messenger *m, m_file_recv_control_cb *function)
 {
     m->file_filecontrol = function;
 }
 
 /* Set the callback for file data.
- *
- *  Function(Tox *tox, uint32_t friendnumber, uint32_t filenumber, uint64_t position, uint8_t *data, size_t length, void *userdata)
- *
  */
 void callback_file_data(Messenger *m, m_file_recv_chunk_cb *function)
 {
     m->file_filedata = function;
 }
 
 /* Set the callback for file request chunk.
- *
- *  Function(Tox *tox, uint32_t friendnumber, uint32_t filenumber, uint64_t position, size_t length, void *userdata)
- *
  */
 void callback_file_reqchunk(Messenger *m, m_file_chunk_request_cb *function)
 {
@@ -1766,11 +1753,7 @@ static int handle_filecontrol(Messenger *m, int32_t friendnumber, uint8_t receiv
     }
 }
 
-/**************************************/
-
 /* Set the callback for msi packets.
- *
- *  Function(Messenger *m, int friendnumber, uint8_t *data, uint16_t length, void *userdata)
  */
 void m_callback_msi_packet(Messenger *m, m_msi_packet_cb *function, void *userdata)
 {