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.

1 files changed, 18 insertions, 33 deletions

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.
  */