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.

16 files changed, 82 insertions, 120 deletions

diff --git a/toxcore/DHT.c b/toxcore/DHT.c
index 55116bc0..fb2e125d 100644
--- 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
index 06a7e012..13f7ce20 100644
--- 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
index b1be2600..c3d06014 100644
--- 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
index e08758e7..ddd04518 100644
--- 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,12 +992,10 @@ 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)
 {
@@ -1007,9 +1003,6 @@ void callback_file_sendrequest(Messenger *m, m_file_recv_cb *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)
 {
@@ -1017,9 +1010,6 @@ void callback_file_control(Messenger *m, m_file_recv_control_cb *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)
 {
@@ -1027,9 +1017,6 @@ void callback_file_data(Messenger *m, m_file_recv_chunk_cb *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)
 {
diff --git a/toxcore/Messenger.h b/toxcore/Messenger.h
index 4d2b1b20..85f730cf 100644
--- a/toxcore/Messenger.h
+++ b/toxcore/Messenger.h
@@ -19,7 +19,7 @@
 #define MAX_NAME_LENGTH 128
 /* TODO(irungentoo): this must depend on other variable. */
 #define MAX_STATUSMESSAGE_LENGTH 1007
-/* Used for TCP relays in Messenger struct (may need to be % 2 == 0)*/
+/* Used for TCP relays in Messenger struct (may need to be `% 2 == 0`)*/
 #define NUM_SAVED_TCP_RELAYS 8
 /* This cannot be bigger than 256 */
 #define MAX_CONCURRENT_FILE_PIPES 256
@@ -300,7 +300,7 @@ struct Messenger {
     Messenger_Options options;
 };
 
-/* 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.
  */
@@ -490,40 +490,40 @@ int m_set_usertyping(Messenger *m, int32_t friendnumber, uint8_t is_typing);
 int m_get_istyping(const Messenger *m, int32_t friendnumber);
 
 /* Set the function that will be executed when a friend request is received.
- *  Function format is function(uint8_t * public_key, uint8_t * data, size_t length)
+ *  Function format is `function(uint8_t * public_key, uint8_t * data, size_t length)`
  */
 void m_callback_friendrequest(Messenger *m, m_friend_request_cb *function);
 
 /* Set the function that will be executed when a message from a friend is received.
- *  Function format is: function(uint32_t friendnumber, unsigned int type, uint8_t * message, uint32_t length)
+ *  Function format is: `function(uint32_t friendnumber, unsigned int type, uint8_t * message, uint32_t length)`
  */
 void m_callback_friendmessage(Messenger *m, m_friend_message_cb *function);
 
 /* Set the callback for name changes.
- *  Function(uint32_t friendnumber, uint8_t *newname, size_t length)
+ *  `Function(uint32_t friendnumber, uint8_t *newname, size_t length)`
  *  You are not responsible for freeing newname.
  */
 void m_callback_namechange(Messenger *m, m_friend_name_cb *function);
 
 /* Set the callback for status message changes.
- *  Function(uint32_t friendnumber, uint8_t *newstatus, size_t length)
+ *  `Function(uint32_t friendnumber, uint8_t *newstatus, size_t length)`
  *
  *  You are not responsible for freeing newstatus
  */
 void m_callback_statusmessage(Messenger *m, m_friend_status_message_cb *function);
 
 /* Set the callback for status type changes.
- *  Function(uint32_t friendnumber, Userstatus kind)
+ *  `Function(uint32_t friendnumber, Userstatus kind)`
  */
 void m_callback_userstatus(Messenger *m, m_friend_status_cb *function);
 
 /* Set the callback for typing changes.
- *  Function(uint32_t friendnumber, uint8_t is_typing)
+ *  `Function(uint32_t friendnumber, uint8_t is_typing)`
  */
 void m_callback_typingchange(Messenger *m, m_friend_typing_cb *function);
 
 /* Set the callback for read receipts.
- *  Function(uint32_t friendnumber, uint32_t receipt)
+ *  `Function(uint32_t friendnumber, uint32_t receipt)`
  *
  *  If you are keeping a record of returns from m_sendmessage,
  *  receipt might be one of those values, meaning the message
@@ -534,14 +534,14 @@ void m_callback_typingchange(Messenger *m, m_friend_typing_cb *function);
 void m_callback_read_receipt(Messenger *m, m_friend_read_receipt_cb *function);
 
 /* Set the callback for connection status changes.
- *  function(uint32_t friendnumber, uint8_t status)
+ *  `function(uint32_t friendnumber, uint8_t status)`
  *
  *  Status:
  *    0 -- friend went offline after being previously online.
  *    1 -- friend went online.
  *
- *  Note that this callback is not called when adding friends, thus the "after
- *  being previously online" part.
+ *  Note that this callback is not called when adding friends, thus the
+ *  "after being previously online" part.
  *  It's assumed that when adding friends, their connection status is offline.
  */
 void m_callback_connectionstatus(Messenger *m, m_friend_connection_status_cb *function);
@@ -556,11 +556,9 @@ void m_callback_connectionstatus_internal_av(Messenger *m, m_friend_connectionst
  */
 void m_callback_core_connection(Messenger *m, m_self_connection_status_cb *function);
 
-/**********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);
 
@@ -571,34 +569,23 @@ void m_callback_conference_invite(Messenger *m, m_conference_invite_cb *function
  */
 int send_conference_invite_packet(const Messenger *m, int32_t friendnumber, const uint8_t *data, uint16_t length);
 
-/****************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);
 
 
 /* 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);
 
 /* 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);
 
 /* 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);
 
@@ -673,11 +660,9 @@ int file_data(const Messenger *m, int32_t friendnumber, uint32_t filenumber, uin
  */
 uint64_t file_dataremaining(const Messenger *m, int32_t friendnumber, uint8_t filenumber, uint8_t send_receive);
 
-/*************** A/V related ******************/
+/** A/V related */
 
 /* Set the callback for msi packets.
- *
- *  Function(Messenger *m, uint32_t friendnumber, uint8_t *data, uint16_t length, void *userdata)
  */
 void m_callback_msi_packet(Messenger *m, m_msi_packet_cb *function, void *userdata);
 
@@ -696,7 +681,7 @@ int m_msi_packet(const Messenger *m, int32_t friendnumber, const uint8_t *data,
 int m_callback_rtp_packet(Messenger *m, int32_t friendnumber, uint8_t byte,
                           m_lossy_rtp_packet_cb *function, void *object);
 
-/**********************************************/
+/** CUSTOM PACKETS */
 
 /* Set handlers for custom lossy packets.
  *
@@ -731,7 +716,7 @@ void custom_lossless_packet_registerhandler(Messenger *m, m_friend_lossless_pack
  */
 int send_custom_lossless_packet(const Messenger *m, int32_t friendnumber, const uint8_t *data, uint32_t length);
 
-/**********************************************/
+/** Messenger constructor/destructor/operations. */
 
 typedef enum Messenger_Error {
     MESSENGER_ERROR_NONE,
@@ -783,7 +768,7 @@ uint8_t *messenger_save(const Messenger *m, uint8_t *data);
  *
  * @param data Data to load.
  * @param length Length of data.
- * @param type Type of section (STATE_TYPE_*).
+ * @param type Type of section (`STATE_TYPE_*`).
  * @param status Result of loading section is stored here if the section is handled.
  * @return true iff section handled.
  */
diff --git a/toxcore/crypto_core.c b/toxcore/crypto_core.c
index 5875bca2..5538b1b8 100644
--- a/toxcore/crypto_core.c
+++ b/toxcore/crypto_core.c
@@ -242,7 +242,7 @@ int32_t decrypt_data(const uint8_t *public_key, const uint8_t *secret_key, const
 /* Increment the given nonce by 1. */
 void increment_nonce(uint8_t *nonce)
 {
-    /* TODO(irungentoo): use increment_nonce_number(nonce, 1) or
+    /* TODO(irungentoo): use `increment_nonce_number(nonce, 1)` or
      * sodium_increment (change to little endian).
      *
      * NOTE don't use breaks inside this loop.
diff --git a/toxcore/friend_requests.h b/toxcore/friend_requests.h
index 04863948..e3a03a51 100644
--- a/toxcore/friend_requests.h
+++ b/toxcore/friend_requests.h
@@ -30,14 +30,12 @@ typedef void fr_friend_request_cb(void *object, const uint8_t *public_key, const
                                   void *user_data);
 
 /* Set the function that will be executed when a friend request for us is received.
- *  Function format is function(uint8_t * public_key, uint8_t * data, size_t length, void * userdata)
  */
 void callback_friendrequest(Friend_Requests *fr, fr_friend_request_cb *function, void *object);
 
 typedef int filter_function_cb(const uint8_t *public_key, void *user_data);
 
 /* Set the function used to check if a friend request should be displayed to the user or not.
- * Function format is int function(uint8_t * public_key, void * userdata)
  * It must return 0 if the request is ok (anything else if it is bad.)
  */
 void set_filter_function(Friend_Requests *fr, filter_function_cb *function, void *userdata);
diff --git a/toxcore/group.c b/toxcore/group.c
index fd7b2ac4..3b9c7f40 100644
--- a/toxcore/group.c
+++ b/toxcore/group.c
@@ -1131,7 +1131,7 @@ static void remove_conn_reason(Group_Chats *g_c, uint32_t groupnumber, uint16_t
 
 /* Creates a new groupchat and puts it in the chats array.
  *
- * type is one of GROUPCHAT_TYPE_*
+ * type is one of `GROUPCHAT_TYPE_*`
  *
  * return group number on success.
  * return -1 on failure.
@@ -1334,9 +1334,9 @@ int group_set_max_frozen(const Group_Chats *g_c, uint32_t groupnumber, uint32_t
 
 /* List all the (frozen, if frozen is true) peers in the group chat.
  *
- * Copies the names of the peers to the name[length][MAX_NAME_LENGTH] array.
+ * Copies the names of the peers to the `name[length][MAX_NAME_LENGTH]` array.
  *
- * Copies the lengths of the names to lengths[length]
+ * Copies the lengths of the names to `lengths[length]`
  *
  * returns the number of peers on success.
  *
@@ -1418,11 +1418,11 @@ int group_get_type(const Group_Chats *g_c, uint32_t groupnumber)
     return g->type;
 }
 
-/* Copies the unique id of group_chat[groupnumber] into id.
-*
-* return false on failure.
-* return true on success.
-*/
+/* Copies the unique id of `group_chat[groupnumber]` into `id`.
+ *
+ * return false on failure.
+ * return true on success.
+ */
 bool conference_get_id(const Group_Chats *g_c, uint32_t groupnumber, uint8_t *id)
 {
     const Group_c *g = get_group_c(g_c, groupnumber);
@@ -2018,7 +2018,7 @@ static void handle_friend_invite_packet(Messenger *m, uint32_t friendnumber, con
     }
 }
 
-/* Find index of friend in the close list;
+/* Find index of friend in the close list.
  *
  * returns index on success
  * returns -1 on failure.
@@ -2621,7 +2621,7 @@ static Message_Info *find_message_slot_or_reject(uint32_t message_number, uint8_
 
 /* Stores message info in peer->last_message_infos.
  *
- * return true if message should be processed;
+ * return true if message should be processed.
  * return false otherwise.
  */
 static bool check_message_info(uint32_t message_number, uint8_t message_id, Group_Peer *peer)
@@ -3194,7 +3194,7 @@ static uint32_t saved_conf_size(const Group_c *g)
     return len;
 }
 
-/* Save a future message number; the save will remain valid until we have sent
+/* Save a future message number. The save will remain valid until we have sent
  * this many more messages. */
 #define SAVE_OFFSET_MESSAGE_NUMBER (1 << 16)
 #define SAVE_OFFSET_LOSSY_MESSAGE_NUMBER (1 << 13)
diff --git a/toxcore/group.h b/toxcore/group.h
index d74d561d..c5601378 100644
--- a/toxcore/group.h
+++ b/toxcore/group.h
@@ -76,8 +76,8 @@ typedef enum Groupchat_Close_Type {
 #define GROUPCHAT_CLOSE_REASON_INTRODUCER  (1 << 2)
 
 typedef struct Groupchat_Close {
-    uint8_t type; /* GROUPCHAT_CLOSE_* */
-    uint8_t reasons; /* bit field with flags GROUPCHAT_CLOSE_REASON_* */
+    uint8_t type; /* `GROUPCHAT_CLOSE_*` */
+    uint8_t reasons; /* bit field with flags `GROUPCHAT_CLOSE_REASON_*` */
     uint32_t number;
     uint16_t group_number;
 } Groupchat_Close;
@@ -222,7 +222,7 @@ void g_callback_peer_list_changed(Group_Chats *g_c, peer_list_changed_cb *functi
 
 /* Creates a new groupchat and puts it in the chats array.
  *
- * type is one of GROUPCHAT_TYPE_*
+ * type is one of `GROUPCHAT_TYPE_*`
  *
  * return group number on success.
  * return -1 on failure.
@@ -357,9 +357,9 @@ int group_peernumber_is_ours(const Group_Chats *g_c, uint32_t groupnumber, int p
 
 /* List all the (frozen, if frozen is true) peers in the group chat.
  *
- * Copies the names of the peers to the name[length][MAX_NAME_LENGTH] array.
+ * Copies the names of the peers to the `name[length][MAX_NAME_LENGTH]` array.
  *
- * Copies the lengths of the names to lengths[length]
+ * Copies the lengths of the names to `lengths[length]`
  *
  * returns the number of peers on success.
  *
@@ -398,11 +398,11 @@ uint32_t copy_chatlist(const Group_Chats *g_c, uint32_t *out_list, uint32_t list
  */
 int group_get_type(const Group_Chats *g_c, uint32_t groupnumber);
 
-/* Copies the unique id of group_chat[groupnumber] into id.
-*
-* return false on failure.
-* return true on success.
-*/
+/* Copies the unique id of `group_chat[groupnumber]` into id.
+ *
+ * return false on failure.
+ * return true on success.
+ */
 bool conference_get_id(const Group_Chats *g_c, uint32_t groupnumber, uint8_t *id);
 
 int32_t conference_by_id(const Group_Chats *g_c, const uint8_t *id);
@@ -471,7 +471,7 @@ uint8_t *conferences_save(const Group_Chats *g_c, uint8_t *data);
  *
  * @param data Data to load
  * @param length Length of data
- * @param type Type of section (STATE_TYPE_*)
+ * @param type Type of section (`STATE_TYPE_*`)
  * @param status Result of loading section is stored here if the section is handled.
  * @return true iff section handled.
  */
diff --git a/toxcore/net_crypto.c b/toxcore/net_crypto.c
index 4eacb250..6a69bb5b 100644
--- a/toxcore/net_crypto.c
+++ b/toxcore/net_crypto.c
@@ -30,17 +30,17 @@ typedef struct Packet_Data {
 typedef struct Packets_Array {
     Packet_Data *buffer[CRYPTO_PACKET_BUFFER_SIZE];
     uint32_t  buffer_start;
-    uint32_t  buffer_end; /* packet numbers in array: {buffer_start, buffer_end) */
+    uint32_t  buffer_end; /* packet numbers in array: `{buffer_start, buffer_end)` */
 } Packets_Array;
 
 typedef enum Crypto_Conn_State {
-    CRYPTO_CONN_FREE = 0,            /* the connection slot is free; this value is 0 so it is valid after
-                                      * crypto_memzero(...) of the parent struct
+    CRYPTO_CONN_FREE = 0,            /* the connection slot is free. This value is 0 so it is valid after
+                                      * `crypto_memzero(...)` of the parent struct
                                       */
     CRYPTO_CONN_NO_CONNECTION,       /* the connection is allocated, but not yet used */
     CRYPTO_CONN_COOKIE_REQUESTING,   /* we are sending cookie request packets */
     CRYPTO_CONN_HANDSHAKE_SENT,      /* we are sending handshake packets */
-    CRYPTO_CONN_NOT_CONFIRMED,       /* we are sending handshake packets;
+    CRYPTO_CONN_NOT_CONFIRMED,       /* we are sending handshake packets.
                                       * we have received one from the other, but no data */
     CRYPTO_CONN_ESTABLISHED,         /* the connection is established */
 } Crypto_Conn_State;
@@ -725,7 +725,7 @@ static int send_packet_to(Net_Crypto *c, int crypt_connection_id, const uint8_t
     return -1;
 }
 
-/** START: Array Related functions **/
+/** START: Array Related functions */
 
 
 /* Return number of packets in array
@@ -1045,7 +1045,7 @@ static int handle_request_packet(Mono_Time *mono_time, const Logger *log, Packet
     return requested;
 }
 
-/** END: Array Related functions **/
+/** END: Array Related functions */
 
 #define MAX_DATA_DATA_PACKET_SIZE (MAX_CRYPTO_PACKET_SIZE - (1 + sizeof(uint16_t) + CRYPTO_MAC_SIZE))
 
diff --git a/toxcore/net_crypto.h b/toxcore/net_crypto.h
index 736a3dc3..3885a1ba 100644
--- a/toxcore/net_crypto.h
+++ b/toxcore/net_crypto.h
@@ -16,9 +16,9 @@
 
 #include <pthread.h>
 
-/*** Crypto payloads. ***/
+/** Crypto payloads. */
 
-/** Ranges. **/
+/** Ranges. */
 
 /* Packets in this range are reserved for net_crypto internal use. */
 #define PACKET_ID_RANGE_RESERVED_START 0
@@ -41,7 +41,7 @@
 #define PACKET_ID_RANGE_LOSSY_CUSTOM_END 254
 #define PACKET_ID_RANGE_LOSSY_END 254
 
-/** Messages. **/
+/** Messages. */
 
 #define PACKET_ID_PADDING 0 // Denotes padding
 #define PACKET_ID_REQUEST 1 // Used to request unreceived packets
diff --git a/toxcore/network.c b/toxcore/network.c
index ab0003e0..67122ea3 100644
--- a/toxcore/network.c
+++ b/toxcore/network.c
@@ -414,7 +414,7 @@ static void loglogdata(const Logger *log, const char *message, const uint8_t *bu
 {
     char ip_str[IP_NTOA_LEN];
 
-    if (res < 0) { /* Windows doesn't necessarily know %zu */
+    if (res < 0) { /* Windows doesn't necessarily know `%zu` */
         int error = net_error();
         const char *strerror = net_new_strerror(error);
         LOGGER_TRACE(log, "[%2u] %s %3u%c %s:%u (%u: %s) | %04x%04x",
@@ -842,14 +842,14 @@ Networking_Core *new_networking_ex(const Logger *log, IP ip, uint16_t port_from,
         net_kill_strerror(strerror);
     }
 
-    /* a hanging program or a different user might block the standard port;
-     * as long as it isn't a parameter coming from the commandline,
-     * try a few ports after it, to see if we can find a "free" one
+    /* A hanging program or a different user might block the standard port.
+     * As long as it isn't a parameter coming from the commandline,
+     * try a few ports after it, to see if we can find a "free" one.
      *
-     * if we go on without binding, the first sendto() automatically binds to
-     * a free port chosen by the system (i.e. anything from 1024 to 65535)
+     * If we go on without binding, the first sendto() automatically binds to
+     * a free port chosen by the system (i.e. anything from 1024 to 65535).
      *
-     * returning NULL after bind fails has both advantages and disadvantages:
+     * Returning NULL after bind fails has both advantages and disadvantages:
      * advantage:
      *   we can rely on getting the port in the range 33445..33450, which
      *   enables us to tell joe user to open their firewall to a small range
diff --git a/toxcore/network.h b/toxcore/network.h
index 9fbefc28..b7e8ede2 100644
--- a/toxcore/network.h
+++ b/toxcore/network.h
@@ -95,7 +95,7 @@ typedef enum Net_Packet_Type {
     NET_PACKET_CRYPTO               = 0x20, /* Encrypted data packet ID. */
     NET_PACKET_LAN_DISCOVERY        = 0x21, /* LAN discovery packet ID. */
 
-    /* See: docs/Prevent_Tracking.txt and onion.{c,h} */
+    /* See: `docs/Prevent_Tracking.txt` and `onion.{c,h}` */
     NET_PACKET_ONION_SEND_INITIAL   = 0x80,
     NET_PACKET_ONION_SEND_1         = 0x81,
     NET_PACKET_ONION_SEND_2         = 0x82,
@@ -288,11 +288,11 @@ void ipport_copy(IP_Port *target, const IP_Port *source);
  *     IP versions are acceptable
  * @param extra can be NULL and is only set in special circumstances, see returns
  *
- * returns in *to a valid IPAny (v4/v6),
- *     prefers v6 if ip.family was TOX_AF_UNSPEC and both available
- * returns in *extra an IPv4 address, if family was TOX_AF_UNSPEC and *to is TOX_AF_INET6
+ * returns in `*to` a valid IPAny (v4/v6),
+ *     prefers v6 if `ip.family` was TOX_AF_UNSPEC and both available
+ * returns in `*extra` an IPv4 address, if family was TOX_AF_UNSPEC and `*to` is TOX_AF_INET6
  *
- * @return 0 on failure, TOX_ADDR_RESOLVE_* on success.
+ * @return 0 on failure, `TOX_ADDR_RESOLVE_*` on success.
  */
 int addr_resolve(const char *address, IP *to, IP *extra);
 
@@ -305,8 +305,8 @@ int addr_resolve(const char *address, IP *to, IP *extra);
  *     IP versions are acceptable
  * @param extra can be NULL and is only set in special circumstances, see returns
  *
- * returns in *tro a matching address (IPv6 or IPv4)
- * returns in *extra, if not NULL, an IPv4 address, if to->family was TOX_AF_UNSPEC
+ * returns in `*to` a matching address (IPv6 or IPv4)
+ * returns in `*extra`, if not NULL, an IPv4 address, if `to->family` was TOX_AF_UNSPEC
  *
  * @return true on success, false on failure
  */
diff --git a/toxcore/onion.c b/toxcore/onion.c
index 4b7d446f..32a3e88d 100644
--- a/toxcore/onion.c
+++ b/toxcore/onion.c
@@ -135,7 +135,7 @@ int create_onion_path(const DHT *dht, Onion_Path *new_path, const Node_format *n
     return 0;
 }
 
-/* Dump nodes in onion path to nodes of length num_nodes;
+/* Dump nodes in onion path to nodes of length num_nodes.
  *
  * return -1 on failure.
  * return 0 on success.
diff --git a/toxcore/onion.h b/toxcore/onion.h
index f125f3c3..da145081 100644
--- a/toxcore/onion.h
+++ b/toxcore/onion.h
@@ -140,8 +140,6 @@ int send_onion_response(Networking_Core *net, IP_Port dest, const uint8_t *data,
 int onion_send_1(const Onion *onion, const uint8_t *plain, uint16_t len, IP_Port source, const uint8_t *nonce);
 
 /* Set the callback to be called when the dest ip_port doesn't have TOX_AF_INET6 or TOX_AF_INET as the family.
- *
- * Format: function(void *object, IP_Port dest, uint8_t *data, uint16_t length)
  */
 void set_callback_handle_recv_1(Onion *onion, onion_recv_1_cb *function, void *object);
 
diff --git a/toxcore/onion_client.c b/toxcore/onion_client.c
index dcec7ba8..e161928b 100644
--- a/toxcore/onion_client.c
+++ b/toxcore/onion_client.c
@@ -1686,7 +1686,7 @@ static void do_announce(Onion_Client *onion_c)
 
             uint32_t pathnum = list_nodes[i].path_used % NUMBER_ONION_PATHS;
 
-            /* A node/path is considered 'stable', and can be pinged less
+            /* A node/path is considered "stable", and can be pinged less
              * aggressively, if it has survived for at least TIME_TO_STABLE
              * and the latest packets sent to it are not timing out.
              */