core/conv: Minor documentation improvements

Signed-off-by: Sylvain Munaut <tnt@246tNt.com>

2 files changed, 19 insertions, 12 deletions

diff --git a/include/osmocom/core/conv.h b/include/osmocom/core/conv.h
index db3058cd..ba490b45 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 @@ int  osmo_conv_encode(const struct osmo_conv_code *code,
 /* 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 @@ struct osmo_conv_decoder {
 	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 0416d272..00a5532d 100644
--- a/src/conv.c
+++ b/src/conv.c
@@ -156,6 +156,7 @@ osmo_conv_encode_finish(struct osmo_conv_encoder *encoder,
  *  \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