more API documentation

3 files changed, 26 insertions, 0 deletions

diff --git a/include/gapk/codecs.h b/include/gapk/codecs.h
index e8d7027..00c34b5 100644
--- a/include/gapk/codecs.h
+++ b/include/gapk/codecs.h
@@ -38,17 +38,26 @@ enum codec_type {
 
 #include <gapk/formats.h>	/* need to import here because or enum interdep */
 
+/*! call-back for actual codec conversion function
+ *  \param[in] state opaque state pointer (returned by codec->init)
+ *  \param[out] dst caller-allocated buffer for output data
+ *  \param[in] src input data
+ *  \param[in] src_len length of input data \a src
+ *  \returns number of output bytes written to \a dst; negative on error */
 typedef int (*codec_conv_cb_t)(void *state, uint8_t *dst, const uint8_t *src, unsigned int src_len);
 
 struct codec_desc {
 	enum codec_type		type;
 	const char *		name;
 	const char *		description;
+	/*! canonical frame size (in bytes); 0 in case of variable length */
 	unsigned int		canon_frame_len;
 
 	enum format_type	codec_enc_format_type;	/* what the encoder provides */
 	enum format_type	codec_dec_format_type;	/* what to give the decoder */
+	/*! codec initialization function pointer, returns opaque state */
 	void *			(*codec_init)(void);
+	/*! codec exit function pointer, gets passed opaque state */
 	void			(*codec_exit)(void *state);
 	codec_conv_cb_t		codec_encode;
 	codec_conv_cb_t		codec_decode;
diff --git a/include/gapk/formats.h b/include/gapk/formats.h
index 5e1a262..4b2418a 100644
--- a/include/gapk/formats.h
+++ b/include/gapk/formats.h
@@ -53,6 +53,11 @@ enum format_type {
 
 #include <gapk/codecs.h>	/* need to import here because or enum interdep */
 
+/*! call-back for actual format conversion function
+ *  \param[out] dst caller-allocated buffer for output data
+ *  \param[in] src input data
+ *  \param[in] src_len length of input data \a src
+ *  \returns number of output bytes written to \a dst; negative on error */
 typedef int (*fmt_conv_cb_t)(uint8_t *dst, const uint8_t *src, unsigned int src_len);
 
 struct format_desc {
@@ -61,11 +66,14 @@ struct format_desc {
 	const char *		name;
 	const char *		description;
 
+	/*! length of frames in this format (as opposed to canonical) */
 	unsigned int		frame_len;
 	fmt_conv_cb_t		conv_from_canon;
 	fmt_conv_cb_t		conv_to_canon;
 
+	/*! length of a (global) header at start of file */
 	unsigned int		header_len;
+	/*! exact match for (global) header at start of file */
 	const uint8_t *		header;
 };
 
diff --git a/include/gapk/procqueue.h b/include/gapk/procqueue.h
index b2ee0ee..d9a5546 100644
--- a/include/gapk/procqueue.h
+++ b/include/gapk/procqueue.h
@@ -26,9 +26,18 @@
 struct pq;
 
 struct pq_item {
+	/*! input frame size (in bytes). '0' in case of variable frames */
 	int len_in;
+	/*! output frame size (in bytes). '0' in case of variable frames */
 	int len_out;
+	/*! opaque state */
 	void *state;
+	/*! call-back for actual format conversion function
+	 *  \param[in] state opaque state pointer
+	 *  \param[out] out caller-allocated buffer for output data
+	 *  \param[in] in input data
+	 *  \param[in] in_len length of input data \a in
+	 *  \returns number of output bytes written to \a out; negative on error */
 	int  (*proc)(void *state, uint8_t *out, const uint8_t *in, unsigned int in_len);
 	void (*exit)(void *state);
 };