av1: add doxygen comments (#384)

include/re_av1.h

@@ -7,19 +7,19 @@
 
 /* OBU (Open Bitstream Units) */
 
-/*
- * OBU Header
+/**
+ * AV1 OBU Header
  *
  *     0 1 2 3 4 5 6 7
  *    +-+-+-+-+-+-+-+-+
  *    |F| type  |X|S|-| (REQUIRED)
  *    +-+-+-+-+-+-+-+-+
  */
 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);

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;

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;

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)