From 7cd36fc5a96579bdf9f3d7e4f5aec1c5ad26c873 Mon Sep 17 00:00:00 2001
From: "Alfred E. Heggestad" <alfred.heggestad@gmail.com>
Date: Fri, 3 Jun 2022 09:25:52 +0200
Subject: [PATCH] av1: add doxygen comments (#384)

---
 include/re_av1.h | 20 ++++++++++----------
 src/av1/depack.c |  8 ++++++++
 src/av1/obu.c    | 37 +++++++++++++++++++++++++++++++++++++
 src/av1/pkt.c    | 14 ++++++++++++++
 4 files changed, 69 insertions(+), 10 deletions(-)

diff --git a/include/re_av1.h b/include/re_av1.h
index 312c7238c..6619ab1c1 100644
--- a/include/re_av1.h
+++ b/include/re_av1.h
@@ -7,8 +7,8 @@
 
 /* OBU (Open Bitstream Units) */
 
-/*
- * OBU Header
+/**
+ * AV1 OBU Header
  *
  *     0 1 2 3 4 5 6 7
  *    +-+-+-+-+-+-+-+-+
@@ -16,10 +16,10 @@
  *    +-+-+-+-+-+-+-+-+
  */
 struct av1_obu_hdr {
-	unsigned type:4;  /* type           */
-	bool x;           /* extension flag */
-	bool s;           /* has size field */
-	size_t size;      /* payload size   */
+	unsigned type:4;  /**< OBU type       */
+	bool x;           /**< Extension flag */
+	bool s;           /**< Has size field */
+	size_t size;      /**< Payload size   */
 };
 
 int av1_leb128_encode(struct mbuf *mb, size_t value);
@@ -46,10 +46,10 @@ int av1_packetize(bool *newp, bool marker, uint64_t rtp_ts,
 
 /** AV1 Aggregation Header */
 struct av1_aggr_hdr {
-	unsigned z:1;  /* continuation of an OBU fragment from prev packet  */
-	unsigned y:1;  /* last OBU element will continue in the next packet */
-	unsigned w:2;  /* number of OBU elements in the packet              */
-	unsigned n:1;  /* first packet of a coded video sequence            */
+	unsigned z:1;  /**< Continuation of OBU fragment from prev packet */
+	unsigned y:1;  /**< Last OBU element will continue in next packe  */
+	unsigned w:2;  /**< Number of OBU elements in the packet          */
+	unsigned n:1;  /**< First packet of a coded video sequence        */
 };
 
 int av1_aggr_hdr_decode(struct av1_aggr_hdr *hdr, struct mbuf *mb);
diff --git a/src/av1/depack.c b/src/av1/depack.c
index 1741d02ac..54a6f086e 100644
--- a/src/av1/depack.c
+++ b/src/av1/depack.c
@@ -10,6 +10,14 @@
 #include <re_av1.h>
 
 
+/**
+ * Decode an AV1 Aggregation header from mbuffer
+ *
+ * @param hdr Decoded aggregation header
+ * @param mb  Mbuffer to decode from
+ *
+ * @return 0 if success, otherwise errorcode
+ */
 int av1_aggr_hdr_decode(struct av1_aggr_hdr *hdr, struct mbuf *mb)
 {
 	uint8_t v;
diff --git a/src/av1/obu.c b/src/av1/obu.c
index 938869620..225212459 100644
--- a/src/av1/obu.c
+++ b/src/av1/obu.c
@@ -16,6 +16,15 @@
 #include <re_dbg.h>
 
 
+/**
+ * Encode a number into LEB128 format, which is an unsigned integer
+ * represented by a variable number of little-endian bytes.
+ *
+ * @param mb    Mbuffer to encode into
+ * @param value Value to encode
+ *
+ * @return 0 if success, otherwise errorcode
+ */
 int av1_leb128_encode(struct mbuf *mb, size_t value)
 {
 	int err = 0;
@@ -38,6 +47,15 @@ int av1_leb128_encode(struct mbuf *mb, size_t value)
 }
 
 
+/**
+ * Decode a number in LEB128 format, which is an unsigned integer
+ * represented by a variable number of little-endian bytes.
+ *
+ * @param mb    Mbuffer to decode from
+ * @param value Decoded value, set on return
+ *
+ * @return 0 if success, otherwise errorcode
+ */
 int av1_leb128_decode(struct mbuf *mb, size_t *value)
 {
 	size_t ret = 0;
@@ -67,6 +85,17 @@ int av1_leb128_decode(struct mbuf *mb, size_t *value)
 }
 
 
+/**
+ * Encode an OBU into an mbuffer
+ *
+ * @param mb       Mbuffer to encode into
+ * @param type     OBU type
+ * @param has_size True to use the 'has_size' field
+ * @param len      Number of bytes
+ * @param payload  Optional OBU payload
+ *
+ * @return 0 if success, otherwise errorcode
+ */
 int av1_obu_encode(struct mbuf *mb, uint8_t type, bool has_size,
 		   size_t len, const uint8_t *payload)
 {
@@ -91,6 +120,14 @@ int av1_obu_encode(struct mbuf *mb, uint8_t type, bool has_size,
 }
 
 
+/**
+ * Decode an OBU header from mbuffer
+ *
+ * @param hdr Decoded OBU header
+ * @param mb  Mbuffer to decode from
+ *
+ * @return 0 if success, otherwise errorcode
+ */
 int av1_obu_decode(struct av1_obu_hdr *hdr, struct mbuf *mb)
 {
 	uint8_t val;
diff --git a/src/av1/pkt.c b/src/av1/pkt.c
index 7da10d9b3..66d047851 100644
--- a/src/av1/pkt.c
+++ b/src/av1/pkt.c
@@ -22,6 +22,20 @@ static void hdr_encode(uint8_t hdr[HDR_SIZE],
 }
 
 
+/**
+ * Packetize an AV1 bitstream with one or more OBUs
+ *
+ * @param newp    Pointer to new stream flag
+ * @param marker  Set marker bit
+ * @param rtp_ts  RTP timestamp
+ * @param buf     Input buffer
+ * @param len     Buffer length
+ * @param maxlen  Maximum RTP packet size
+ * @param pkth    Packet handler
+ * @param arg     Handler argument
+ *
+ * @return 0 if success, otherwise errorcode
+ */
 int av1_packetize(bool *newp, bool marker, uint64_t rtp_ts,
 		  const uint8_t *buf, size_t len, size_t maxlen,
 		  av1_packet_h *pkth, void *arg)