cleanup: Sync doc comments between .h and .c files.

toxcore/Messenger.c

@@ -728,8 +728,8 @@ int m_set_userstatus(Messenger *m, uint8_t status)
 /**
  * Guaranteed to be at most MAX_STATUSMESSAGE_LENGTH.
  *
- * returns the length of friendnumber's status message, including null on success.
- * returns -1 on failure.
+ * @return the length of friendnumber's status message, including null on success.
+ * @retval -1 on failure.
  */
 int m_get_statusmessage_size(const Messenger *m, int32_t friendnumber)
 {
@@ -1000,7 +1000,7 @@ static void set_friend_status(Messenger *m, int32_t friendnumber, uint8_t status
 /*** CONFERENCES */
 
 
-/** Set the callback for conference invites. */
+/** @brief Set the callback for conference invites. */
 void m_callback_conference_invite(Messenger *m, m_conference_invite_cb *function)
 {
     m->conference_invite = function;
@@ -1020,25 +1020,25 @@ bool send_conference_invite_packet(const Messenger *m, int32_t friendnumber, con
 /*** FILE SENDING */
 
 
-/** Set the callback for file send requests. */
+/** @brief Set the callback for file send requests. */
 void callback_file_sendrequest(Messenger *m, m_file_recv_cb *function)
 {
     m->file_sendrequest = function;
 }
 
-/** Set the callback for file control requests. */
+/** @brief Set the callback for file control requests. */
 void callback_file_control(Messenger *m, m_file_recv_control_cb *function)
 {
     m->file_filecontrol = function;
 }
 
-/** Set the callback for file data. */
+/** @brief Set the callback for file data. */
 void callback_file_data(Messenger *m, m_file_recv_chunk_cb *function)
 {
     m->file_filedata = function;
 }
 
-/** Set the callback for file request chunk. */
+/** @brief Set the callback for file request chunk. */
 void callback_file_reqchunk(Messenger *m, m_file_chunk_request_cb *function)
 {
     m->file_reqchunk = function;
@@ -1128,13 +1128,14 @@ static bool file_sendrequest(const Messenger *m, int32_t friendnumber, uint8_t f
 }
 
 /** @brief Send a file send request.
+ *
  * Maximum filename length is 255 bytes.
+ *
  * @return file number on success
  * @retval -1 if friend not found.
  * @retval -2 if filename length invalid.
  * @retval -3 if no more file sending slots left.
  * @retval -4 if could not send packet (friend offline).
- *
  */
 long int new_filesender(const Messenger *m, int32_t friendnumber, uint32_t file_type, uint64_t filesize,
                         const uint8_t *file_id, const uint8_t *filename, uint16_t filename_length)
@@ -1738,7 +1739,7 @@ static int handle_filecontrol(Messenger *m, int32_t friendnumber, bool outbound,
     }
 }
 
-/** Set the callback for msi packets. */
+/** @brief Set the callback for msi packets. */
 void m_callback_msi_packet(Messenger *m, m_msi_packet_cb *function, void *userdata)
 {
     m->msi_packet = function;
@@ -2381,7 +2382,7 @@ uint32_t messenger_run_interval(const Messenger *m)
     return crypto_interval;
 }
 
-/** The main loop that needs to be run at least 20 times per second. */
+/** @brief The main loop that needs to be run at least 20 times per second. */
 void do_messenger(Messenger *m, void *userdata)
 {
     // Add the TCP relays, but only if this is the first time calling do_messenger

toxcore/TCP_connection.c

@@ -365,7 +365,7 @@ int send_packet_tcp_connection(const TCP_Connections *tcp_c, int connections_num
     return sent_any ? 0 : -1;
 }
 
-/** @brief Return a random TCP connection number for use in send_tcp_onion_request.
+/** @brief Return a TCP connection number for use in send_tcp_onion_request.
  *
  * TODO(irungentoo): This number is just the index of an array that the elements
  * can change without warning.
@@ -459,21 +459,21 @@ int tcp_send_oob_packet_using_relay(const TCP_Connections *tcp_c, const uint8_t
     return tcp_send_oob_packet(tcp_c, tcp_con_number, public_key, packet, length);
 }
 
-/** Set the callback for TCP data packets. */
+/** @brief Set the callback for TCP data packets. */
 void set_packet_tcp_connection_callback(TCP_Connections *tcp_c, tcp_data_cb *tcp_data_callback, void *object)
 {
     tcp_c->tcp_data_callback = tcp_data_callback;
     tcp_c->tcp_data_callback_object = object;
 }
 
-/** Set the callback for TCP oob data packets. */
+/** @brief Set the callback for TCP oob data packets. */
 void set_oob_packet_tcp_connection_callback(TCP_Connections *tcp_c, tcp_oob_cb *tcp_oob_callback, void *object)
 {
     tcp_c->tcp_oob_callback = tcp_oob_callback;
     tcp_c->tcp_oob_callback_object = object;
 }
 
-/** Set the callback for TCP onion packets. */
+/** @brief Set the callback for TCP onion packets. */
 void set_onion_packet_tcp_connection_callback(TCP_Connections *tcp_c, tcp_onion_cb *tcp_onion_callback, void *object)
 {
     tcp_c->tcp_onion_callback = tcp_onion_callback;
@@ -1339,7 +1339,8 @@ static bool copy_tcp_relay_conn(const TCP_Connections *tcp_c, Node_format *tcp_r
     return true;
 }
 
-/** @brief Copy a maximum of max_num random TCP relays we are connected to to tcp_relays.
+/** @brief Copy a maximum of max_num TCP relays we are connected to to tcp_relays.
+ *
  * NOTE that the family of the copied ip ports will be set to TCP_INET or TCP_INET6.
  *
  * return number of relays copied to tcp_relays on success.

toxcore/TCP_connection.h

@@ -91,7 +91,7 @@ non_null()
 int send_packet_tcp_connection(const TCP_Connections *tcp_c, int connections_number, const uint8_t *packet,
                                uint16_t length);
 
-/** @brief Return a random TCP connection number for use in send_tcp_onion_request.
+/** @brief Return a TCP connection number for use in send_tcp_onion_request.
  *
  * TODO(irungentoo): This number is just the index of an array that the elements
  * can change without warning.

toxcore/group.h

@@ -93,7 +93,7 @@ void g_callback_peer_list_changed(Group_Chats *g_c, peer_list_changed_cb *functi
 
 /** @brief Creates a new groupchat and puts it in the chats array.
  *
- * type is one of `GROUPCHAT_TYPE_*`
+ * @param type is one of `GROUPCHAT_TYPE_*`
  *
  * @return group number on success.
  * @retval -1 on failure.

toxcore/util.c

@@ -20,7 +20,7 @@
 #include "crypto_core.h" /* for CRYPTO_PUBLIC_KEY_SIZE */
 
 
-/** id functions */
+/** Equality function for public keys. */
 bool pk_equal(const uint8_t *dest, const uint8_t *src)
 {
     return public_key_eq(dest, src);