chore: Fix up a few source code comment and style issues.

Tokstyle no longer allows:
* Includes inside an `extern "C"`
* Comments on function definition and declaration to be different.
* Doxygen comments commenting on other doxygen comments.

.cirrus.yml

@@ -1,7 +1,7 @@
 ---
 cirrus-ci_task:
   container:
-    image: toxchat/toktok-stack:0.0.28-third_party
+    image: toxchat/toktok-stack:0.0.29-third_party
     cpu: 2
     memory: 2G
   configure_script:
@@ -19,7 +19,7 @@ cirrus-ci_task:
 
 cimple_task:
   container:
-    image: toxchat/toktok-stack:0.0.28-third_party
+    image: toxchat/toktok-stack:0.0.29-third_party
     cpu: 2
     memory: 4G
   configure_script:

toxav/bwcontroller.h

@@ -8,11 +8,6 @@
 #include "../toxcore/Messenger.h"
 #include "../toxcore/tox.h"
 
-#ifndef TOX_DEFINED
-#define TOX_DEFINED
-typedef struct Tox Tox;
-#endif /* TOX_DEFINED */
-
 typedef struct BWController_s BWController;
 
 typedef void m_cb(BWController *bwc, uint32_t friend_number, float todo, void *user_data);

toxav/groupav.h

@@ -8,7 +8,7 @@
 #include "../toxcore/group.h"
 #include "../toxcore/tox.h"
 
-/* Audio encoding/decoding */
+// Audio encoding/decoding
 #include <opus.h>
 
 #define GROUP_AUDIO_PACKET_ID 192

toxav/msi.c

@@ -74,9 +74,10 @@ static void handle_pop(MSICall *call, const MSIMessage *msg);
 static void handle_msi_packet(Messenger *m, uint32_t friend_number, const uint8_t *data, uint16_t length, void *object);
 
 
-/**
+/*
  * Public functions
  */
+
 void msi_register_callback(MSISession *session, msi_action_cb *callback, MSICallbackID id)
 {
     if (!session) {

toxav/rtp.c

@@ -740,8 +740,13 @@ int rtp_stop_receiving(RTPSession *session)
 }
 
 /**
- * @param data is raw vpx data.
+ * Send a frame of audio or video data, chunked in \ref RTPMessage instances.
- * @param length is the length of the raw data.
+ *
+ * @param session The A/V session to send the data for.
+ * @param data A byte array of length \p length.
+ * @param length The number of bytes to send from @p data.
+ * @param is_keyframe Whether this video frame is a key frame. If it is an
+ *   audio frame, this parameter is ignored.
  */
 int rtp_send_data(RTPSession *session, const uint8_t *data, uint32_t length,
                   bool is_keyframe, const Logger *log)

toxav/rtp.h

@@ -9,6 +9,7 @@
 
 #include "../toxcore/Messenger.h"
 #include "../toxcore/logger.h"
+#include "../toxcore/tox.h"
 
 #include <stdbool.h>
 
@@ -16,11 +17,6 @@
 extern "C" {
 #endif
 
-#ifndef TOX_DEFINED
-#define TOX_DEFINED
-typedef struct Tox Tox;
-#endif /* TOX_DEFINED */
-
 /**
  * RTPHeader serialised size in bytes.
  */

toxcore/logger.c

@@ -58,9 +58,10 @@ static const Logger logger_stderr = {
 };
 #endif
 
-/**
+/*
  * Public Functions
  */
+
 Logger *logger_new(void)
 {
     return (Logger *)calloc(1, sizeof(Logger));

toxcore/tox.h

@@ -3,29 +3,6 @@
  * Copyright © 2013 Tox project.
  */
 
-/*
- * The Tox public API.
- */
-#ifndef C_TOXCORE_TOXCORE_TOX_H
-#define C_TOXCORE_TOXCORE_TOX_H
-
-#include <stdbool.h>
-#include <stddef.h>
-#include <stdint.h>
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-
-/*******************************************************************************
- * `tox.h` SHOULD NOT BE EDITED MANUALLY – any changes should be made to
- * `tox.api.h`, located in `toxcore/`. For instructions on how to
- * generate `tox.h` from `tox.api.h` please refer to `docs/apidsl.md`
- ******************************************************************************/
-
-
-
 /**
  * @page core Public core API for Tox clients.
  *
@@ -64,8 +41,7 @@ extern "C" {
  *
  * Integer constants and the memory layout of publicly exposed structs are not
  * part of the ABI.
- */
+ *
-/**
  * @subsection events Events and callbacks
  *
  * Events are handled by callbacks. One callback can be registered per event.
@@ -87,8 +63,7 @@ extern "C" {
  * Old style callbacks that are registered together with a user data pointer
  * receive that pointer as argument when they are called. They can each have
  * their own user data pointer of their own type.
- */
+ *
-/**
  * @subsection threading Threading implications
  *
  * It is possible to run multiple concurrent threads with a Tox instance for
@@ -122,6 +97,26 @@ extern "C" {
  * memory, the length may have become invalid, and the call to
  * tox_self_get_name may cause undefined behaviour.
  */
+#ifndef C_TOXCORE_TOXCORE_TOX_H
+#define C_TOXCORE_TOXCORE_TOX_H
+
+#include <stdbool.h>
+#include <stddef.h>
+#include <stdint.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+
+/*******************************************************************************
+ * `tox.h` SHOULD NOT BE EDITED MANUALLY – any changes should be made to
+ * `tox.api.h`, located in `toxcore/`. For instructions on how to
+ * generate `tox.h` from `tox.api.h` please refer to `docs/apidsl.md`
+ ******************************************************************************/
+
+
+
 /**
  * The Tox instance type. All the state associated with a connection is held
  * within the instance. Multiple instances can exist and operate concurrently.

toxencryptsave/toxencryptsave.c

@@ -151,18 +151,21 @@ Tox_Pass_Key *tox_pass_key_derive_with_salt(const uint8_t *passphrase, size_t pp
 }
 
 /**
- * Encrypt arbitrary with a key produced by `tox_derive_key_*`. The output
+ * Encrypt a plain text with a key produced by tox_pass_key_derive or tox_pass_key_derive_with_salt.
- * array must be at least data_len + TOX_PASS_ENCRYPTION_EXTRA_LENGTH bytes long.
- * key must be TOX_PASS_KEY_LENGTH bytes.
- * If you already have a symmetric key from somewhere besides this module, simply
- * call encrypt_data_symmetric in toxcore/crypto_core directly.
  *
- * returns true on success
+ * The output array must be at least `plaintext_len + TOX_PASS_ENCRYPTION_EXTRA_LENGTH`
+ * bytes long.
+ *
+ * @param plaintext A byte array of length `plaintext_len`.
+ * @param plaintext_len The length of the plain text array. Bigger than 0.
+ * @param ciphertext The cipher text array to write the encrypted data to.
+ *
+ * @return true on success.
  */
-bool tox_pass_key_encrypt(const Tox_Pass_Key *key, const uint8_t *data, size_t data_len, uint8_t *out,
+bool tox_pass_key_encrypt(const Tox_Pass_Key *key, const uint8_t *plaintext, size_t plaintext_len,
-                          Tox_Err_Encryption *error)
+                          uint8_t *ciphertext, Tox_Err_Encryption *error)
 {
-    if (data_len == 0 || !data || !key || !out) {
+    if (plaintext_len == 0 || !plaintext || !key || !ciphertext) {
         SET_ERROR_PARAMETER(error, TOX_ERR_ENCRYPTION_NULL);
         return 0;
     }
@@ -175,21 +178,21 @@ bool tox_pass_key_encrypt(const Tox_Pass_Key *key, const uint8_t *data, size_t d
     // need them to decrypt the data
 
     /* first add the magic number */
-    memcpy(out, TOX_ENC_SAVE_MAGIC_NUMBER, TOX_ENC_SAVE_MAGIC_LENGTH);
+    memcpy(ciphertext, TOX_ENC_SAVE_MAGIC_NUMBER, TOX_ENC_SAVE_MAGIC_LENGTH);
-    out += TOX_ENC_SAVE_MAGIC_LENGTH;
+    ciphertext += TOX_ENC_SAVE_MAGIC_LENGTH;
 
     /* then add the rest prefix */
-    memcpy(out, key->salt, crypto_pwhash_scryptsalsa208sha256_SALTBYTES);
+    memcpy(ciphertext, key->salt, crypto_pwhash_scryptsalsa208sha256_SALTBYTES);
-    out += crypto_pwhash_scryptsalsa208sha256_SALTBYTES;
+    ciphertext += crypto_pwhash_scryptsalsa208sha256_SALTBYTES;
 
     uint8_t nonce[crypto_box_NONCEBYTES];
     random_nonce(nonce);
-    memcpy(out, nonce, crypto_box_NONCEBYTES);
+    memcpy(ciphertext, nonce, crypto_box_NONCEBYTES);
-    out += crypto_box_NONCEBYTES;
+    ciphertext += crypto_box_NONCEBYTES;
 
     /* now encrypt */
-    if (encrypt_data_symmetric(key->key, nonce, data, data_len, out)
+    if (encrypt_data_symmetric(key->key, nonce, plaintext, plaintext_len, ciphertext)
-            != data_len + crypto_box_MACBYTES) {
+            != plaintext_len + crypto_box_MACBYTES) {
         SET_ERROR_PARAMETER(error, TOX_ERR_ENCRYPTION_FAILED);
         return 0;
     }

toxencryptsave/toxencryptsave.h

@@ -10,15 +10,15 @@
 #ifndef C_TOXCORE_TOXENCRYPTSAVE_TOXENCRYPTSAVE_H
 #define C_TOXCORE_TOXENCRYPTSAVE_TOXENCRYPTSAVE_H
 
-#ifdef __cplusplus
-extern "C" {
-#endif
-
 #include <stdbool.h>
 #include <stddef.h>
 #include <stdint.h>
 
 
+#ifdef __cplusplus
+extern "C" {
+#endif
+
 /*******************************************************************************
  *
  * This module is organized into two parts.