core/conv: Minor documentation improvements
Signed-off-by: Sylvain Munaut <tnt@246tNt.com>
diff --git a/include/osmocom/core/conv.h b/include/osmocom/core/conv.h
index db3058c..ba490b4 100644
--- a/include/osmocom/core/conv.h
+++ b/include/osmocom/core/conv.h
@@ -35,25 +35,31 @@
#include <osmocom/core/bits.h>
-/*! \brief structure describing a given convolutional code */
+/*! \brief structure describing a given convolutional code
+ *
+ * The only required fields are N,K and the next_output/next_state arrays. The
+ * other can be left to default value of zero depending on what the code does.
+ * If 'len' is left at 0 then only the low level API can be used.
+ */
struct osmo_conv_code {
- int N;
- int K;
- int len;
+ int N; /*!< \brief Inverse of code rate */
+ int K; /*!< \brief Constraint length */
+ int len; /*!< \brief # of data bits */
- const uint8_t (*next_output)[2];
- const uint8_t (*next_state)[2];
+ const uint8_t (*next_output)[2];/*!< \brief Next output array */
+ const uint8_t (*next_state)[2]; /*!< \brief Next state array */
- const uint8_t *next_term_output;
- const uint8_t *next_term_state;
+ const uint8_t *next_term_output;/*!< \brief Flush termination output */
+ const uint8_t *next_term_state; /*!< \brief Flush termination state */
- const int *puncture;
+ const int *puncture; /*!< \brief Punctured bits indexes */
};
/* Encoding */
/* Low level API */
+
/*! \brief convolutional encoder state */
struct osmo_conv_encoder {
const struct osmo_conv_code *code; /*!< \brief for which code? */
@@ -76,10 +82,10 @@
/* Decoding */
/* Low level API */
+
/*! \brief convolutional decoder state */
struct osmo_conv_decoder {
- /*! \brief description of convolutional code */
- const struct osmo_conv_code *code;
+ const struct osmo_conv_code *code; /*!< \brief for which code? */
int n_states; /*!< \brief number of states */
@@ -88,7 +94,7 @@
int o_idx; /*!< \brief output index */
int p_idx; /*!< \brief puncture index */
- unsigned int *ae; /*!< \brief accumulater error */
+ unsigned int *ae; /*!< \brief accumulated error */
unsigned int *ae_next; /*!< \brief next accumulated error (tmp in scan) */
uint8_t *state_history; /*!< \brief state history [len][n_states] */
};
diff --git a/src/conv.c b/src/conv.c
index 0416d27..00a5532 100644
--- a/src/conv.c
+++ b/src/conv.c
@@ -156,6 +156,7 @@
* \param[in] code description of convolutional code to be used
* \param[in] input array of unpacked bits (uncoded)
* \param[out] output array of unpacked bits (encoded)
+ * \return Number of produced output bits
*
* This is an all-in-one function, taking care of
* \ref osmo_conv_init, \ref osmo_conv_encode_raw and