gr-fec/cc_encoder: Fix and improve documentation

* Fix wrong Voyager polynomials. The binary and decimal representation
  which must be passed as an argument to the block, however, is
  correct.

* Clarify how the generator polynomials are to be represented. Add the
  important note that an uncommonly used representation is required.

* Mention that start_state must be possibly reversed and that
  start_state is used to flush the encoder in terminated mode.

* Mention support for inversion of the output of a generator polynomial.

* Improve description of tailbiting and terminated mode.

* Mention valid values for parameters.

1 files changed, 45 insertions, 19 deletions

diff --git a/gr-fec/include/gnuradio/fec/cc_encoder.h b/gr-fec/include/gnuradio/fec/cc_encoder.h
index 26f3a4a85..c5e7d0275 100644
--- a/gr-fec/include/gnuradio/fec/cc_encoder.h
+++ b/gr-fec/include/gnuradio/fec/cc_encoder.h
@@ -71,23 +71,22 @@ namespace code {
  * samples into the encoder, and the output stream is
  * continually encoded.
  *
- * \li 'CC_TERMINATED': is a mode designed for packet-based
- * systems. This mode adds rate*(k-1) bits to the output as a
- * way to help flush the decoder.
+ * \li 'CC_TERMINATED': is a mode designed for packet-based systems. This mode
+ * flushes the encoder with K-1 bits which adds rate*(K-1) bits to the output.
+ * This improves the protection of the last bits of a block and helps the
+ * decoder.
  *
- * \li 'CC_TAILBITING': is another packet-based method. Instead of
- * adding bits onto the end of the packet, this mode will
- * continue the code between the payloads of packets by
- * pre-initializing the state of the new packet based on the
- * state of the last packet for (k-1) bits.
+ * \li 'CC_TAILBITING': is another packet-based method. Instead of adding bits
+ * onto the end of a packet (as with 'CC_TERMINATED'), this mode will
+ * pre-initialize the state of the encoder with a packet’s last (k-1) bits.
  *
  * \li 'CC_TRUNCATED': a truncated code always resets the registers
  * to the \p start_state between frames.
  *
- * A common convolutional encoder uses K=7, Rate=1/2,
- * Polynomials=[109, 79]. This is the Voyager code from NASA:
- * \li   109: b(1101101) --> 1 + x   + x^3 + x^4 + x^6
- * \li   79:  b(1001111) --> 1 + x^3 + x^4 + x^5 + x^6
+ * A common convolutional encoder uses K=7, Rate=1/2, and the polynomials
+ * \li  1 + x^2 + x^3 + x^5 + x^6
+ * \li  1 + x   + x^2 + x^3 + x^6
+ * This is the Voyager code from NASA.
  *
  * Another encoder class is provided with gr-fec called the
  * gr::fec::code::ccsds_encoder, which implements the above code
@@ -100,14 +99,41 @@ public:
     /*!
      * Build a convolutional code encoding FEC API object.
      *
-     * \param frame_size Number of bits per frame. If using in the
-     *        tagged stream style, this is the maximum allowable
-     *        number of bits per frame.
-     * \param k Constraint length (K) of the encoder.
-     * \param rate Inverse of the coder's rate
+     * \param frame_size Number of bits per frame; must be > 1. If using in the
+     *        tagged stream style, this is the maximum allowable number of bits
+     *        per frame.
+     * \param k Constraint length (K) of the encoder; must be in the range [2, 31].
+     *        K = 1 implies a code without memory which does not make sense;
+     *        upper limit is due the way the polynomials of the code are passed
+     *        in \p polys.
+     * \param rate Inverse of the coder's rate; must be > 1.
      *             (rate=2 means 2 output bits per 1 input).
-     * \param polys Vector of polynomials as integers.
-     * \param start_state Initialization state of the shift register.
+     * \param polys Vector of polynomials as integers. The least significant bit
+     *              (LSB) denotes the coefficient of exponent zero of the coding
+     *              polynomial. The position of the most significant set bit
+     *              (zero based counting) is \p K-1. Note: this representation
+     *              is reversed compared to the common representation as found
+     *              in most books and references. The common representation puts
+     *              the coefficient of the highest exponent into the LSB and the
+     *              coefficient of exponent zero is the highest set bit.
+     *              Example: The common binary representation of the Voyager
+     *              code polynomials (see above) is 1011011 and 1111001; the
+     *              octal representation is 133 and 171. For this block, the
+     *              binary representation must be reversed: 1101101 and 1001111;
+     *              octal this is 155 and 117; decimal this is 109 and 79. Some
+     *              standards (e.g. CCSDS 131.0-B-3) require the inversion of
+     *              some outputs. This is supported by providing the negative
+     *              value of the polynomial, e.g. -109.
+     * \param start_state Initialization state of the shift register; must be in
+     *                    range [0, 2^(K-1)-1] where K is the constraint length.
+     *                    The bits in \p start_state are also used to flush the
+     *                    encoder in mode 'CC_TERMINATED'.
+     *                    Note: Most books and references use a shift register
+     *                    shifting from left to right. This implementation,
+     *                    however, shifts from right to left. This means that
+     *                    the start state must be reversed. (The different shift
+     *                    direction is also the reason why the polynomials must
+     *                    be reversed as described above.)
      * \param mode cc_mode_t mode of the encoding.
      * \param padded true if the encoded frame should be padded
      *               to the nearest byte.