docs: Make crypto_core.h appear on doxygen.

.github/scripts/cmake-linux

@@ -33,5 +33,6 @@ cmake -B_build -H. -GNinja \
 cmake --build _build --parallel "$NPROC" --target install -- -k 0
 
 cd _build # pushd
-ctest -j50 --output-on-failure --rerun-failed --repeat until-pass:6
+ctest -j50 --output-on-failure --rerun-failed --repeat until-pass:6 ||
+  ctest -j50 --output-on-failure --rerun-failed --repeat until-pass:6
 cd - # popd

.github/scripts/cmake-osx

@@ -31,5 +31,6 @@ cmake -B_build -H. \
 
 cd _build # pushd
 make "-j$NPROC" -k install
-ctest -j50 --output-on-failure --rerun-failed --repeat until-pass:6
+ctest -j50 --output-on-failure --rerun-failed --repeat until-pass:6 ||
+  ctest -j50 --output-on-failure --rerun-failed --repeat until-pass:6
 cd - # popd

.github/settings.yml

@@ -42,6 +42,7 @@ branches:
           - "docker-bootstrap-node-websocket"
           - "docker-toxcore-js"
           - "mypy"
+          - "netlify/c-toxcore/deploy-preview"
           - "sonar-scan"
 
 # Labels specific to c-toxcore.

docs/Doxyfile

@@ -2236,7 +2236,7 @@ INCLUDE_FILE_PATTERNS  =
 # recursively expanded use the := operator instead of the = operator.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-PREDEFINED             = DOXYGEN_SKIP
+PREDEFINED             = DOXYGEN_IGNORE
 
 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this
 # tag can be used to specify a list of macro names that should be expanded. The

netlify.toml

@@ -5,6 +5,6 @@ command = """\
   else \
     git clone --depth=1 https://github.com/jothepro/doxygen-awesome-css.git;
   fi && \
-  doxygen .doxygen.conf \
+  doxygen docs/Doxyfile \
   """
 publish = "_docs/html"

other/docker/doxygen/Dockerfile

@@ -9,9 +9,9 @@ RUN apk add --no-cache doxygen git graphviz \
  && git clone --depth=1 https://github.com/jothepro/doxygen-awesome-css.git /work/doxygen-awesome-css
 WORKDIR /work
 COPY . /work/
-RUN cat .doxygen.conf > doxygen.conf \
- && echo "WARN_AS_ERROR = YES" >> doxygen.conf \
- && doxygen doxygen.conf
+RUN cat docs/Doxyfile > Doxyfile \
+ && echo "WARN_AS_ERROR = YES" >> Doxyfile \
+ && doxygen Doxyfile
 
 FROM nginx:alpine
 COPY --from=build /work/_docs/html/ /usr/share/nginx/html/

toxav/toxav.h

@@ -3,7 +3,7 @@
  * Copyright © 2013-2015 Tox project.
  */
 
-/** @file toxav.h
+/** @file
  * @brief Public audio/video API for Tox clients.
  *
  * This API can handle multiple calls. Each call has its state, in very rare
@@ -832,7 +832,7 @@ bool toxav_groupchat_av_enabled(Tox *tox, uint32_t groupnumber);
 #endif
 
 //!TOKSTYLE-
-#ifdef DOXYGEN_IGNORE
+#ifndef DOXYGEN_IGNORE
 
 typedef Toxav_Err_Call TOXAV_ERR_CALL;
 typedef Toxav_Err_New TOXAV_ERR_NEW;

toxcore/crypto_core.c

@@ -182,11 +182,6 @@ bool public_key_valid(const uint8_t *public_key)
     return 1;
 }
 
-/**
- * Fast encrypt/decrypt operations. Use if this is not a one-time communication.
- * encrypt_precompute does the shared-key generation once so it does not have
- * to be performed on every encrypt/decrypt.
- */
 int32_t encrypt_precompute(const uint8_t *public_key, const uint8_t *secret_key,
                            uint8_t *shared_key)
 {
@@ -320,10 +315,6 @@ int32_t decrypt_data(const uint8_t *public_key, const uint8_t *secret_key, const
     return ret;
 }
 
-/**
- * Increment the given nonce by 1 in big endian (rightmost byte incremented
- * first).
- */
 void increment_nonce(uint8_t *nonce)
 {
     /* TODO(irungentoo): use `increment_nonce_number(nonce, 1)` or
@@ -343,10 +334,6 @@ void increment_nonce(uint8_t *nonce)
     }
 }
 
-/**
- * Increment the given nonce by a given number. The number should be in host
- * byte order.
- */
 void increment_nonce_number(uint8_t *nonce, uint32_t increment)
 {
     /* NOTE don't use breaks inside this loop
@@ -369,17 +356,11 @@ void increment_nonce_number(uint8_t *nonce, uint32_t increment)
     }
 }
 
-/**
- * Fill the given nonce with random bytes.
- */
 void random_nonce(uint8_t *nonce)
 {
     random_bytes(nonce, crypto_box_NONCEBYTES);
 }
 
-/**
- * Fill a key CRYPTO_SYMMETRIC_KEY_SIZE big with random bytes.
- */
 void new_symmetric_key(uint8_t *key)
 {
     random_bytes(key, CRYPTO_SYMMETRIC_KEY_SIZE);

toxcore/crypto_core.h

@@ -3,8 +3,8 @@
  * Copyright © 2013 Tox project.
  */
 
-/**
- * Functions for the core crypto.
+/** @file
+ * @brief Functions for the core crypto.
  */
 #ifndef C_TOXCORE_TOXCORE_CRYPTO_CORE_H
 #define C_TOXCORE_TOXCORE_CRYPTO_CORE_H
@@ -18,74 +18,76 @@ extern "C" {
 #endif
 
 /**
- * The number of bytes in a Tox public key used for encryption.
+ * @brief The number of bytes in a Tox public key used for encryption.
  */
 #define CRYPTO_PUBLIC_KEY_SIZE         32
 
 /**
- * The number of bytes in a Tox secret key used for encryption.
+ * @brief The number of bytes in a Tox secret key used for encryption.
  */
 #define CRYPTO_SECRET_KEY_SIZE         32
 
 /**
- * The number of bytes in a shared key computed from public and secret keys.
+ * @brief The number of bytes in a shared key computed from public and secret keys.
  */
 #define CRYPTO_SHARED_KEY_SIZE         32
 
 /**
- * The number of bytes in a symmetric key.
+ * @brief The number of bytes in a symmetric key.
  */
 #define CRYPTO_SYMMETRIC_KEY_SIZE      CRYPTO_SHARED_KEY_SIZE
 
 /**
- * The number of bytes needed for the MAC (message authentication code) in an
+ * @brief The number of bytes needed for the MAC (message authentication code) in an
  * encrypted message.
  */
 #define CRYPTO_MAC_SIZE                16
 
 /**
- * The number of bytes in a nonce used for encryption/decryption.
+ * @brief The number of bytes in a nonce used for encryption/decryption.
  */
 #define CRYPTO_NONCE_SIZE              24
 
 /**
- * The number of bytes in a SHA256 hash.
+ * @brief The number of bytes in a SHA256 hash.
  */
 #define CRYPTO_SHA256_SIZE             32
 
 /**
- * The number of bytes in a SHA512 hash.
+ * @brief The number of bytes in a SHA512 hash.
  */
 #define CRYPTO_SHA512_SIZE             64
 
 /**
- * A `bzero`-like function which won't be optimised away by the compiler. Some
- * compilers will inline `bzero` or `memset` if they can prove that there will
- * be no reads to the written data. Use this function if you want to be sure the
- * memory is indeed zeroed.
+ * @brief A `bzero`-like function which won't be optimised away by the compiler.
+ *
+ * Some compilers will inline `bzero` or `memset` if they can prove that there
+ * will be no reads to the written data. Use this function if you want to be
+ * sure the memory is indeed zeroed.
  */
 void crypto_memzero(void *data, size_t length);
 
 /**
- * Compute a SHA256 hash (32 bytes).
+ * @brief Compute a SHA256 hash (32 bytes).
  */
 void crypto_sha256(uint8_t *hash, const uint8_t *data, size_t length);
 
 /**
- * Compute a SHA512 hash (64 bytes).
+ * @brief Compute a SHA512 hash (64 bytes).
  */
 void crypto_sha512(uint8_t *hash, const uint8_t *data, size_t length);
 
 /**
- * Compare 2 public keys of length CRYPTO_PUBLIC_KEY_SIZE, not vulnerable to
+ * @brief Compare 2 public keys of length @ref CRYPTO_PUBLIC_KEY_SIZE, not vulnerable to
  * timing attacks.
  *
- * @return 0 if both mem locations of length are equal, -1 if they are not.
+ * @retval 0 if both mem locations of length are equal
+ * @retval -1 if they are not
  */
 int32_t public_key_cmp(const uint8_t *pk1, const uint8_t *pk2);
 
 /**
- * Compare 2 SHA512 checksums of length CRYPTO_SHA512_SIZE, not vulnerable to
+ * @brief Compare 2 SHA512 checksums of length CRYPTO_SHA512_SIZE, not vulnerable to
  * timing attacks.
  *
  * @return 0 if both mem locations of length are equal, -1 if they are not.
@@ -93,27 +95,27 @@ int32_t public_key_cmp(const uint8_t *pk1, const uint8_t *pk2);
 int32_t crypto_sha512_cmp(const uint8_t *cksum1, const uint8_t *cksum2);
 
 /**
- * Return a random 8 bit integer.
+ * @brief Return a random 8 bit integer.
  */
 uint8_t random_u08(void);
 
 /**
- * Return a random 16 bit integer.
+ * @brief Return a random 16 bit integer.
  */
 uint16_t random_u16(void);
 
 /**
- * Return a random 32 bit integer.
+ * @brief Return a random 32 bit integer.
  */
 uint32_t random_u32(void);
 
 /**
- * Return a random 64 bit integer.
+ * @brief Return a random 64 bit integer.
  */
 uint64_t random_u64(void);
 
 /**
- * Return a random 32 bit integer between 0 and upper_bound (excluded).
+ * @brief Return a random 32 bit integer between 0 and upper_bound (excluded).
  *
  * On libsodium builds this function guarantees a uniform distribution of possible outputs.
  * On vanilla NACL builds this function is equivalent to `random() % upper_bound`.
@@ -121,68 +123,78 @@ uint64_t random_u64(void);
 uint32_t random_range_u32(uint32_t upper_bound);
 
 /**
- * Fill the given nonce with random bytes.
+ * @brief Fill the given nonce with random bytes.
  */
 void random_nonce(uint8_t *nonce);
 
 /**
- * Fill an array of bytes with random values.
+ * @brief Fill an array of bytes with random values.
  */
 void random_bytes(uint8_t *bytes, size_t length);
 
 /**
- * Check if a Tox public key CRYPTO_PUBLIC_KEY_SIZE is valid or not. This
- * should only be used for input validation.
+ * @brief Check if a Tox public key CRYPTO_PUBLIC_KEY_SIZE is valid or not.
+ *
+ * This should only be used for input validation.
  *
  * @return false if it isn't, true if it is.
  */
 bool public_key_valid(const uint8_t *public_key);
 
 /**
- * Generate a new random keypair. Every call to this function is likely to
- * generate a different keypair.
+ * @brief Generate a new random keypair.
+ *
+ * Every call to this function is likely to generate a different keypair.
  */
 int32_t crypto_new_keypair(uint8_t *public_key, uint8_t *secret_key);
 
 /**
- * Derive the public key from a given secret key.
+ * @brief Derive the public key from a given secret key.
  */
 void crypto_derive_public_key(uint8_t *public_key, const uint8_t *secret_key);
 
 /**
- * Encrypt plain text of the given length to encrypted of length +
- * CRYPTO_MAC_SIZE using the public key (CRYPTO_PUBLIC_KEY_SIZE bytes) of the
- * receiver and the secret key of the sender and a CRYPTO_NONCE_SIZE byte
- * nonce.
+ * @brief Encrypt message to send from secret key to public key.
  *
- * @return -1 if there was a problem, length of encrypted data if everything
- * was fine.
+ * Encrypt plain text of the given length to encrypted of
+ * `length + CRYPTO_MAC_SIZE` using the public key (@ref CRYPTO_PUBLIC_KEY_SIZE
+ * bytes) of the receiver and the secret key of the sender and a
+ * @ref CRYPTO_NONCE_SIZE byte nonce.
+ *
+ * @retval -1 if there was a problem.
+ * @retval >=0 length of encrypted data if everything was fine.
  */
 int32_t encrypt_data(const uint8_t *public_key, const uint8_t *secret_key, const uint8_t *nonce, const uint8_t *plain,
                      size_t length, uint8_t *encrypted);
 
 /**
- * Decrypt encrypted text of the given length to plain text of the given length
- * - CRYPTO_MAC_SIZE using the public key (CRYPTO_PUBLIC_KEY_SIZE bytes) of
- * the sender, the secret key of the receiver and a CRYPTO_NONCE_SIZE byte
- * nonce.
+ * @brief Decrypt message from public key to secret key.
  *
- * @return -1 if there was a problem (decryption failed), length of plain text
- * data if everything was fine.
+ * Decrypt encrypted text of the given @p length to plain text of the given
+ * `length - CRYPTO_MAC_SIZE` using the public key (@ref CRYPTO_PUBLIC_KEY_SIZE
+ * bytes) of the sender, the secret key of the receiver and a
+ * @ref CRYPTO_NONCE_SIZE byte nonce.
+ *
+ * @retval -1 if there was a problem (decryption failed).
+ * @retval >=0 length of plain text data if everything was fine.
  */
 int32_t decrypt_data(const uint8_t *public_key, const uint8_t *secret_key, const uint8_t *nonce,
                      const uint8_t *encrypted, size_t length, uint8_t *plain);
 
 /**
- * Fast encrypt/decrypt operations. Use if this is not a one-time communication.
- * encrypt_precompute does the shared-key generation once so it does not have
- * to be performed on every encrypt/decrypt.
+ * @brief Fast encrypt/decrypt operations.
+ *
+ * Use if this is not a one-time communication. @ref encrypt_precompute does the
+ * shared-key generation once so it does not have to be performed on every
+ * encrypt/decrypt.
  */
 int32_t encrypt_precompute(const uint8_t *public_key, const uint8_t *secret_key, uint8_t *shared_key);
 
 /**
- * Encrypts plain of length length to encrypted of length + CRYPTO_MAC_SIZE
- * using a shared key CRYPTO_SYMMETRIC_KEY_SIZE big and a CRYPTO_NONCE_SIZE
+ * @brief Encrypt message with precomputed shared key.
+ *
+ * Encrypts plain of length length to encrypted of length + @ref CRYPTO_MAC_SIZE
+ * using a shared key @ref CRYPTO_SYMMETRIC_KEY_SIZE big and a @ref CRYPTO_NONCE_SIZE
  * byte nonce.
  *
  * @return -1 if there was a problem, length of encrypted data if everything
@@ -192,9 +204,11 @@ int32_t encrypt_data_symmetric(const uint8_t *shared_key, const uint8_t *nonce,
                                uint8_t *encrypted);
 
 /**
+ * @brief Decrypt message with precomputed shared key.
+ *
  * Decrypts encrypted of length length to plain of length length -
- * CRYPTO_MAC_SIZE using a shared key CRYPTO_SHARED_KEY_SIZE big and a
- * CRYPTO_NONCE_SIZE byte nonce.
+ * @ref CRYPTO_MAC_SIZE using a shared key @ref CRYPTO_SHARED_KEY_SIZE big and a
+ * @ref CRYPTO_NONCE_SIZE byte nonce.
  *
  * @return -1 if there was a problem (decryption failed), length of plain data
  * if everything was fine.
@@ -203,39 +217,43 @@ int32_t decrypt_data_symmetric(const uint8_t *shared_key, const uint8_t *nonce,
                                uint8_t *plain);
 
 /**
- * Increment the given nonce by 1 in big endian (rightmost byte incremented
+ * @brief Increment the given nonce by 1 in big endian (rightmost byte incremented
  * first).
  */
 void increment_nonce(uint8_t *nonce);
 
 /**
- * Increment the given nonce by a given number. The number should be in host
- * byte order.
+ * @brief Increment the given nonce by a given number.
+ *
+ * The number should be in host byte order.
  */
 void increment_nonce_number(uint8_t *nonce, uint32_t increment);
 
 /**
- * Fill a key CRYPTO_SYMMETRIC_KEY_SIZE big with random bytes.
+ * @brief Fill a key @ref CRYPTO_SYMMETRIC_KEY_SIZE big with random bytes.
  */
 void new_symmetric_key(uint8_t *key);
 
 /**
- * Locks `length` bytes of memory pointed to by `data`. This will attempt to prevent
- * the specified memory region from being swapped to disk.
+ * @brief Locks `length` bytes of memory pointed to by `data`.
  *
- * Returns true on success.
+ * This will attempt to prevent the specified memory region from being swapped
+ * to disk.
+ *
+ * @return true on success.
  */
 bool crypto_memlock(void *data, size_t length);
 
 /**
- * Unlocks `length` bytes of memory pointed to by `data`. This allows the specified
- * memory region to be swapped to disk.
+ * @brief Unlocks `length` bytes of memory pointed to by `data`.
+ *
+ * This allows the specified memory region to be swapped to disk.
  *
  * This function call has the side effect of zeroing the specified memory region
  * whether or not it succeeds. Therefore it should only be used once the memory
  * is no longer in use.
  *
- * Returns true on success.
+ * @return true on success.
  */
 bool crypto_memunlock(void *data, size_t length);
 

toxcore/ping_array.h

@@ -3,8 +3,8 @@
  * Copyright © 2013 Tox project.
  */
 
-/**
- * Implementation of an efficient array to store that we pinged something.
+/** @file
+ * @brief Implementation of an efficient array to store that we pinged something.
  */
 #ifndef C_TOXCORE_TOXCORE_PING_ARRAY_H
 #define C_TOXCORE_TOXCORE_PING_ARRAY_H
@@ -21,7 +21,7 @@ extern "C" {
 typedef struct Ping_Array Ping_Array;
 
 /**
- * Initialize a Ping_Array.
+ * @brief Initialize a Ping_Array.
  *
  * @param size represents the total size of the array and should be a power of 2.
  * @param timeout represents the maximum timeout in seconds for the entry.
@@ -31,12 +31,12 @@ typedef struct Ping_Array Ping_Array;
 struct Ping_Array *ping_array_new(uint32_t size, uint32_t timeout);
 
 /**
- * Free all the allocated memory in a Ping_Array.
+ * @brief Free all the allocated memory in a @ref Ping_Array.
  */
 void ping_array_kill(struct Ping_Array *array);
 
 /**
- * Add a data with length to the Ping_Array list and return a ping_id.
+ * @brief Add a data with length to the @ref Ping_Array list and return a ping_id.
  *
  * @return ping_id on success, 0 on failure.
  */
@@ -44,7 +44,7 @@ uint64_t ping_array_add(struct Ping_Array *array, const struct Mono_Time *mono_t
                         uint32_t length);
 
 /**
- * Check if ping_id is valid and not timed out.
+ * @brief Check if @p ping_id is valid and not timed out.
  *
  * On success, copies the data into data of length,
  *

toxcore/tox.h

@@ -3,8 +3,7 @@
  * Copyright © 2013 Tox project.
  */
 
-/**
- * @file tox.h
+/** @file
  * @brief Public core API for Tox clients.
  *
  * Every function that can fail takes a function-specific error code pointer
@@ -3231,7 +3230,7 @@ uint16_t tox_self_get_tcp_port(const Tox *tox, Tox_Err_Get_Port *error);
 #endif
 
 //!TOKSTYLE-
-#ifdef DOXYGEN_IGNORE
+#ifndef DOXYGEN_IGNORE
 
 typedef Tox_Err_Options_New TOX_ERR_OPTIONS_NEW;
 typedef Tox_Err_New TOX_ERR_NEW;