add some more comments throughout the code

src/fmt_amr.c

@@ -1,4 +1,4 @@
-/* Classic .amr file format */
+/* Classic .amr file format. Be warned, actaully contains EFR ;) */
 
 /*
  * This file is part of gapk (GSM Audio Pocket Knife).
@@ -26,6 +26,7 @@
 #include <gapk/utils.h>
 
 
+/* conversion function: .amr file -> canonical format */
 static int
 amr_efr_from_canon(uint8_t *dst, const uint8_t *src)
 {
@@ -43,6 +44,7 @@ amr_efr_from_canon(uint8_t *dst, const uint8_t *src)
 	return 0;
 }
 
+/* conversion function: canonical format -> .amr file */
 static int
 amr_efr_to_canon(uint8_t *dst, const uint8_t *src)
 {

src/fmt_gsm.c

@@ -23,6 +23,7 @@
 
 #define GSM_MAGIC 0xd
 
+/* convert canonical -> .gsm */
 static int
 gsm_from_canon(uint8_t *dst, const uint8_t *src)
 {
@@ -35,6 +36,7 @@ gsm_from_canon(uint8_t *dst, const uint8_t *src)
 	return 0;
 }
 
+/* convert .gsm -> canonical */
 static int
 gsm_to_canon(uint8_t *dst, const uint8_t *src)
 {

src/pq_codec.c

@@ -25,6 +25,11 @@
 #include <gapk/procqueue.h>
 
 
+/*! Add a codecl to the processing queue
+ *  \param pq Processing Queue to which the codec is added
+ *  \param[in] codec description
+ *  \param[in] encode (1) or decode (0)
+ *  \returns 0 on success; negative on error */
 int
 pq_queue_codec(struct pq *pq, const struct codec_desc *codec, int enc_dec_n)
 {
@@ -32,10 +37,12 @@ pq_queue_codec(struct pq *pq, const struct codec_desc *codec, int enc_dec_n)
 	const struct format_desc *fmt;
 	struct pq_item *item;
 
+	/* allocate a new item to the processing queue */
 	item = pq_add_item(pq);
 	if (!item)
 		return -ENOMEM;
 
+	/* initialize the codec, if there is an init function */
 	if (codec->codec_init) {
 		item->state = codec->codec_init();
 		if (!item->state)

src/pq_file.c

@@ -86,12 +86,24 @@ pq_queue_file_op(struct pq *pq, FILE *fh, unsigned int blk_len, int in_out_n)
 }
 
 
+/*! Add file input to given processing queue
+ *  This usually only makes sense as first item in the queue
+ *  \param pq Processing Queue to add the input file to
+ *  \param[in] src caller-fopen()ed input file
+ *  \param[in] blk_len block length to be read from file
+ *  \returns 0 on sucess; negative on error */
 int
 pq_queue_file_input(struct pq *pq, FILE *src, unsigned int blk_len)
 {
 	return pq_queue_file_op(pq, src, blk_len, 1);
 }
 
+/*! Add file output to given processing queue
+ *  This usually only makes sense as first item in the queue
+ *  \param pq Processing Queue to add the output file to
+ *  \param[in] dst caller-fopen()ed output file
+ *  \param[in] blk_len block length to be written to file
+ *  \returns 0 on sucess; negative on error */
 int
 pq_queue_file_output(struct pq *pq, FILE *dst, unsigned int blk_len)
 {

src/pq_format.c

@@ -32,6 +32,10 @@ pq_cb_fmt_convert(void *_state, uint8_t *out, const uint8_t *in)
 	return f(out, in);
 }
 
+/*! Add format conversion to processing queue
+ *  \param pq Processing Queue to add conversion to
+ *  \param[in] fmt Format description for conversion
+ *  \param[in] to_from_n convert to (0) or from (1) specified format */
 int
 pq_queue_fmt_convert(struct pq *pq, const struct format_desc *fmt, int to_from_n)
 {

src/pq_rtp.c

@@ -187,6 +187,9 @@ pq_queue_rtp_op(struct pq *pq, int udp_fd, unsigned int blk_len, int in_out_n)
 	state->fd = udp_fd;
 	state->blk_len = blk_len;
 
+	/* as we're working in GSM, the sample clock is 8000 Hz and we
+	 * operate at 50 Hz (20ms) codec frames; 8000/50 = 160 samples
+	 * per RTP frame */
 	state->duration = 160;
 
 	if (in_out_n == 0) {
@@ -213,12 +216,22 @@ pq_queue_rtp_op(struct pq *pq, int udp_fd, unsigned int blk_len, int in_out_n)
 }
 
 
+/*! Add RTP input to processing queue.
+ *  This typically only makes sense as first item in the queue
+ *  \param pq Processing Queue to add this RTP input to
+ *  \param[in] udp_fd UDP file descriptor for the RTP input
+ *  \param[in] blk_len Block Length to read from RTP */
 int
 pq_queue_rtp_input(struct pq *pq, int udp_fd, unsigned int blk_len)
 {
 	return pq_queue_rtp_op(pq, udp_fd, blk_len, 1);
 }
 
+/*! Add RTP output to processing queue.
+ *  This typically only makes sense as last item in the queue
+ *  \param pq Processing Queue to add this RTP output to
+ *  \param[in] udp_fd UDP file descriptor for the RTP output
+ *  \param[in] blk_len Block Length to read from RTP */
 int
 pq_queue_rtp_output(struct pq *pq, int udp_fd, unsigned int blk_len)
 {

src/procqueue.c

@@ -33,12 +33,15 @@ struct pq {
 };
 
 
+/* crate a new (empty) processing queue */
 struct pq *
 pq_create(void)
 {
 	return (struct pq *) calloc(1, sizeof(struct pq));
 }
 
+/*! destroy a processing queue, calls exit() callback of each item
+ *  \param[in] pq Processing Queue to be destroyed */
 void
 pq_destroy(struct pq *pq)
 {
@@ -61,6 +64,9 @@ pq_destroy(struct pq *pq)
 	free(pq);
 }
 
+/*! allocate + add an item to a processing queue; return new item
+ *  \param[in] pq Processing Queue to which item is added
+ *  \returns new PQ item; NULL on error */
 struct pq_item *
 pq_add_item(struct pq *pq)
 {
@@ -78,6 +84,9 @@ pq_add_item(struct pq *pq)
 	return item;
 }
 
+/*! prepare a processing queue; allocates buffers; checks lengths
+ *  \param[in] pq Processing Queue to be prepared
+ *  \returns 0 on succcess; negative on error */
 int
 pq_prepare(struct pq *pq)
 {
@@ -107,6 +116,9 @@ pq_prepare(struct pq *pq)
 	return 0;
 }
 
+/*! execute a processing queue; iterate over processing elements
+ *  \param[in] pq Processing Queue to be executed
+ *  \returns 0 on success; negative on error (if any item returns negative) */
 int
 pq_execute(struct pq *pq)
 {