docs: Clean up doxygen comments to be more doxygen-like.

Author: iphydf

.github/workflows/ci.yml

@@ -28,6 +28,16 @@ jobs:
           (find . -name "*.py" -and -not -name "conanfile.py"; grep -lR '^#!.*python') \
               | xargs -n1 -P8 mypy --strict
 
+  doxygen:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v1
+      - name: Docker Build
+        uses: docker/build-push-action@v2
+        with:
+          file: other/docker/doxygen/Dockerfile
+
   tokstyle:
     runs-on: ubuntu-latest
     steps:
@@ -38,6 +48,13 @@ jobs:
         with:
           file: other/docker/tokstyle/Dockerfile
 
+  cimplefmt:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Run cimplefmt
+        run: other/docker/cimplefmt/run -u $(find tox* -name "*.[ch]")
+
   build-nacl:
     runs-on: ubuntu-latest
     steps:

other/bootstrap_daemon/docker/tox-bootstrapd.sha256

@@ -1 +1 @@
-799360df399d3c82adb10f60765a25b1686e7c091b3a817ae4b2f1aa9db1a622  /usr/local/bin/tox-bootstrapd
+b63168a0b43e9b303947b36e4a2cfdd2acc7f48ebcbad098d092edceed78ac39  /usr/local/bin/tox-bootstrapd

other/docker/cimplefmt/Dockerfile

@@ -0,0 +1,6 @@
+FROM toxchat/haskell:hs-cimple AS cimple
+FROM ubuntu:20.04
+
+COPY --from=cimple /bin/cimplefmt /bin/
+WORKDIR /work
+ENTRYPOINT ["/bin/cimplefmt"]

other/docker/cimplefmt/run

@@ -0,0 +1,8 @@
+#!/bin/sh
+
+if [ "$1" = "-u" ]; then
+  shift
+  docker pull toxchat/haskell:hs-cimple
+  docker build -t toxchat/cimplefmt -f other/docker/cimplefmt/Dockerfile .
+fi
+docker run --rm -v "$PWD:/work" toxchat/cimplefmt "$@"

toxav/groupav.c

@@ -87,7 +87,8 @@ static void terminate_queue(Group_JitterBuffer *q)
     free(q);
 }
 
-/** Return 0 if packet was queued, -1 if it wasn't.
+/** @retval 0 if packet was queued
+ * @retval -1 if it wasn't.
  */
 static int queue(Group_JitterBuffer *q, const Mono_Time *mono_time, Group_Audio_Packet *pk)
 {
@@ -125,7 +126,12 @@ static int queue(Group_JitterBuffer *q, const Mono_Time *mono_time, Group_Audio_
     return 0;
 }
 
-/** success is 0 when there is nothing to dequeue, 1 when there's a good packet, 2 when there's a lost packet */
+/**
+ * success is:
+ * - 0 when there is nothing to dequeue
+ * - 1 when there's a good packet
+ * - 2 when there's a lost packet
+ */
 static Group_Audio_Packet *dequeue(Group_JitterBuffer *q, int *success)
 {
     if (q->top == q->bottom) {
@@ -433,10 +439,10 @@ static int handle_group_audio_packet(void *object, uint32_t groupnumber, uint32_
     return 0;
 }
 
-/** Enable A/V in a groupchat.
+/** @brief Enable A/V in a groupchat.
  *
- * return 0 on success.
- * return -1 on failure.
+ * @retval 0 on success.
+ * @retval -1 on failure.
  */
 int groupchat_enable_av(const Logger *log, Tox *tox, Group_Chats *g_c, uint32_t groupnumber,
                         audio_data_cb *audio_callback, void *userdata)
@@ -475,10 +481,10 @@ int groupchat_enable_av(const Logger *log, Tox *tox, Group_Chats *g_c, uint32_t
     return 0;
 }
 
-/** Disable A/V in a groupchat.
+/** @brief Disable A/V in a groupchat.
  *
- * return 0 on success.
- * return -1 on failure.
+ * @retval 0 on success.
+ * @retval -1 on failure.
  */
 int groupchat_disable_av(const Group_Chats *g_c, uint32_t groupnumber)
 {
@@ -516,17 +522,16 @@ int groupchat_disable_av(const Group_Chats *g_c, uint32_t groupnumber)
     return 0;
 }
 
-/** Return whether A/V is enabled in the groupchat.
- */
+/** Return whether A/V is enabled in the groupchat. */
 bool groupchat_av_enabled(const Group_Chats *g_c, uint32_t groupnumber)
 {
     return group_get_object(g_c, groupnumber) != nullptr;
 }
 
-/** Create and connect to a new toxav group.
+/** @brief Create and connect to a new toxav group.
  *
- * return group number on success.
- * return -1 on failure.
+ * @return group number on success.
+ * @retval -1 on failure.
  */
 int add_av_groupchat(const Logger *log, Tox *tox, Group_Chats *g_c, audio_data_cb *audio_callback, void *userdata)
 {
@@ -544,10 +549,10 @@ int add_av_groupchat(const Logger *log, Tox *tox, Group_Chats *g_c, audio_data_c
     return groupnumber;
 }
 
-/** Join a AV group (you need to have been invited first.)
+/** @brief Join a AV group (you need to have been invited first).
  *
- * returns group number on success
- * returns -1 on failure.
+ * @return group number on success
+ * @retval -1 on failure.
  */
 int join_av_groupchat(const Logger *log, Tox *tox, Group_Chats *g_c, uint32_t friendnumber, const uint8_t *data,
                       uint16_t length, audio_data_cb *audio_callback, void *userdata)
@@ -566,10 +571,10 @@ int join_av_groupchat(const Logger *log, Tox *tox, Group_Chats *g_c, uint32_t fr
     return groupnumber;
 }
 
-/** Send an encoded audio packet to the group chat.
+/** @brief Send an encoded audio packet to the group chat.
  *
- * return 0 on success.
- * return -1 on failure.
+ * @retval 0 on success.
+ * @retval -1 on failure.
  */
 static int send_audio_packet(const Group_Chats *g_c, uint32_t groupnumber, const uint8_t *packet, uint16_t length)
 {
@@ -601,10 +606,10 @@ static int send_audio_packet(const Group_Chats *g_c, uint32_t groupnumber, const
     return 0;
 }
 
-/** Send audio to the group chat.
+/** @brief Send audio to the group chat.
  *
- * return 0 on success.
- * return -1 on failure.
+ * @retval 0 on success.
+ * @retval -1 on failure.
  */
 int group_send_audio(Group_Chats *g_c, uint32_t groupnumber, const int16_t *pcm, unsigned int samples, uint8_t channels,
                      uint32_t sample_rate)

toxav/groupav.h

@@ -19,48 +19,46 @@
 typedef void audio_data_cb(void *tox, uint32_t groupnumber, uint32_t peernumber, const int16_t *pcm,
                            uint32_t samples, uint8_t channels, uint32_t sample_rate, void *userdata);
 
-/** Create and connect to a new toxav group.
+/** @brief Create and connect to a new toxav group.
  *
- * return group number on success.
- * return -1 on failure.
+ * @return group number on success.
+ * @retval -1 on failure.
  */
 int add_av_groupchat(const Logger *log, Tox *tox, Group_Chats *g_c, audio_data_cb *audio_callback, void *userdata);
 
-/** Join a AV group (you need to have been invited first.)
+/** @brief Join a AV group (you need to have been invited first).
  *
- * returns group number on success
- * returns -1 on failure.
+ * @return group number on success
+ * @retval -1 on failure.
  */
 int join_av_groupchat(const Logger *log, Tox *tox, Group_Chats *g_c, uint32_t friendnumber, const uint8_t *data,
-                      uint16_t length,
-                      audio_data_cb *audio_callback, void *userdata);
+                      uint16_t length, audio_data_cb *audio_callback, void *userdata);
 
 
-/** Send audio to the group chat.
+/** @brief Send audio to the group chat.
  *
- * return 0 on success.
- * return -1 on failure.
+ * @retval 0 on success.
+ * @retval -1 on failure.
  */
 int group_send_audio(Group_Chats *g_c, uint32_t groupnumber, const int16_t *pcm, unsigned int samples, uint8_t channels,
                      uint32_t sample_rate);
 
-/** Enable A/V in a groupchat.
+/** @brief Enable A/V in a groupchat.
  *
- * return 0 on success.
- * return -1 on failure.
+ * @retval 0 on success.
+ * @retval -1 on failure.
  */
 int groupchat_enable_av(const Logger *log, Tox *tox, Group_Chats *g_c, uint32_t groupnumber,
                         audio_data_cb *audio_callback, void *userdata);
 
-/** Disable A/V in a groupchat.
+/** @brief Disable A/V in a groupchat.
  *
- * return 0 on success.
- * return -1 on failure.
+ * @retval 0 on success.
+ * @retval -1 on failure.
  */
 int groupchat_disable_av(const Group_Chats *g_c, uint32_t groupnumber);
 
-/** Return whether A/V is enabled in the groupchat.
- */
+/** Return whether A/V is enabled in the groupchat. */
 bool groupchat_av_enabled(const Group_Chats *g_c, uint32_t groupnumber);
 
 #endif // C_TOXCORE_TOXAV_GROUPAV_H

toxav/ring_buffer.c

@@ -27,8 +27,8 @@ bool rb_empty(const RingBuffer *b)
 }
 
 /**
- * returns: NULL on success
- *          input value "p" on FAILURE -> caller can free on failed rb_write
+ * @retval NULL on success
+ * @return input value "p" on failure, so caller can free on failed rb_write
  */
 void *rb_write(RingBuffer *b, void *p)
 {

toxav/rtp.c

@@ -193,7 +193,7 @@ static int8_t get_slot(const Logger *log, struct RTPWorkBufferList *wkbl, bool i
  *
  * If there are no frames ready, we return NULL. If this function returns
  * non-NULL, it transfers ownership of the message to the caller, i.e. the
- * caller is responsible for storing it elsewhere or calling free().
+ * caller is responsible for storing it elsewhere or calling `free()`.
  */
 static struct RTPMessage *process_frame(const Logger *log, struct RTPWorkBufferList *wkbl, uint8_t slot_id)
 {
@@ -345,7 +345,8 @@ static void update_bwc_values(const Logger *log, RTPSession *session, const stru
  *   this is the actual payload length.
  * @param log A logger.
  *
- * @return -1 on error, 0 on success.
+ * @retval -1 on error.
+ * @retval 0 on success.
  */
 static int handle_video_packet(RTPSession *session, const struct RTPHeader *header,
                                const uint8_t *incoming_data, uint16_t incoming_data_length, const Logger *log)
@@ -436,7 +437,8 @@ static int handle_video_packet(RTPSession *session, const struct RTPHeader *head
 }
 
 /**
- * @return -1 on error, 0 on success.
+ * @retval -1 on error.
+ * @retval 0 on success.
  */
 static int handle_rtp_packet(Messenger *m, uint32_t friendnumber, const uint8_t *data, uint16_t length, void *object)
 {
@@ -741,10 +743,10 @@ int rtp_stop_receiving(RTPSession *session)
 }
 
 /**
- * Send a frame of audio or video data, chunked in \ref RTPMessage instances.
+ * Send a frame of audio or video data, chunked in @ref RTPMessage instances.
  *
  * @param session The A/V session to send the data for.
- * @param data A byte array of length \p length.
+ * @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.

toxav/rtp.h

@@ -23,7 +23,7 @@ extern "C" {
 #define RTP_HEADER_SIZE 80
 
 /**
- * Number of 32 bit padding fields between \ref RTPHeader::offset_lower and
+ * Number of 32 bit padding fields between @ref RTPHeader::offset_lower and
  * everything before it.
  */
 #define RTP_PADDING_FIELDS 11
@@ -43,7 +43,7 @@ typedef enum RTP_Type {
 typedef enum RTPFlags {
     /**
      * Support frames larger than 64KiB. The full 32 bit length and offset are
-     * set in \ref RTPHeader::data_length_full and \ref RTPHeader::offset_full.
+     * set in @ref RTPHeader::data_length_full and @ref RTPHeader::offset_full.
      */
     RTP_LARGE_FRAME = 1 << 0,
     /**
@@ -70,14 +70,14 @@ struct RTPHeader {
     /* Non-standard Tox-specific fields */
 
     /**
-     * Bit mask of \c RTPFlags setting features of the current frame.
+     * Bit mask of `RTPFlags` setting features of the current frame.
      */
     uint64_t flags;
 
     /**
-     * The full 32 bit data offset of the current data chunk. The \ref
+     * The full 32 bit data offset of the current data chunk. The @ref
      * offset_lower data member contains the lower 16 bits of this value. For
-     * frames smaller than 64KiB, \ref offset_full and \ref offset_lower are
+     * frames smaller than 64KiB, @ref offset_full and @ref offset_lower are
      * equal.
      */
     uint32_t offset_full;
@@ -106,7 +106,7 @@ struct RTPMessage {
      * This is used in the old code that doesn't deal with large frames, i.e.
      * the audio code or receiving code for old 16 bit messages. We use it to
      * record the number of bytes received so far in a multi-part message. The
-     * multi-part message in the old code is stored in \c RTPSession::mp.
+     * multi-part message in the old code is stored in `RTPSession::mp`.
      */
     uint16_t len;
 
@@ -192,10 +192,10 @@ void rtp_kill(RTPSession *session);
 int rtp_allow_receiving(RTPSession *session);
 int rtp_stop_receiving(RTPSession *session);
 /**
- * Send a frame of audio or video data, chunked in \ref RTPMessage instances.
+ * Send a frame of audio or video data, chunked in @ref RTPMessage instances.
  *
  * @param session The A/V session to send the data for.
- * @param data A byte array of length \p length.
+ * @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.