Add documentation for the frame acquisition block

include/satnogs/frame_acquisition.h

@@ -31,7 +31,32 @@ namespace satnogs
 {
 
 /*!
- * \brief <+description of block+>
+ * \brief A generic frame acquisition block
+ *
+ * A generic frame acquisition block trying to cover a variaty of different
+ * framing schemes.
+ *
+ * The goal of this block is to provide a unified way to acquire the frame
+ * from different satellites with different but closely related framing schemes.
+ * To keep the logic inside the block simple, it assumes that the received
+ * bit stream is ready for framing extraction. Any bit stream coding, like
+ * NRZI, Manchester, etc should be done prior this block.
+ *
+ * Currently the supported are:
+ * - TI framing, constant frame length
+ * - TI framing, variable frame length
+ * - TI like framing, variable frame length with a 12-bit frame legth field
+ * coded with Golay (24, 12, 8) scheme.
+ *
+ * The block supports also an arbitrary descrambler (if provided) using the
+ * satnogs::whitening claass.
+ *
+ * For the CRC calculation (if any) the currently supported schemes are:
+ * - CRC16-CCITT
+ * - Reversed CRC16-CCITT
+ * - CRC16-IBM
+ * - CRC32-CCITT
+ *
  * \ingroup satnogs
  *
  */
@@ -40,10 +65,13 @@ class SATNOGS_API frame_acquisition : virtual public gr::sync_block
 public:
   typedef boost::shared_ptr<frame_acquisition> sptr;
 
+  /**
+   * Different framing schemes variants
+   */
   typedef enum {
-    GENERIC_CONSTANT_FRAME_LEN = 0,
-    GENERIC_VAR_FRAME_LEN,
-    GOLAY24_CODED_FRAME_LEN
+    GENERIC_CONSTANT_FRAME_LEN = 0,//!< TI CCXXX like, constant frame length
+    GENERIC_VAR_FRAME_LEN,         //!< TI CCXXX like, variable frame length
+    GOLAY24_CODED_FRAME_LEN        //!< TI CCXXX like, variable frame length, 12-bit frame legth field coded with Golay (24, 12, 8)
   } variant_t;
 
   typedef enum {
@@ -55,6 +83,43 @@ public:
   } checksum_t;
 
 
+  /**
+   * A generic frame acquisition block trying to cover a variaty of different
+   * framing schemes.
+   *
+   * The goal of this block is to provide a unified way to acquire the frame
+   * from different satellites with different but closely related framing schemes.
+   * To keep the logic inside the block simple, it assumes that the received
+   * bit stream is ready for framing extraction. Any bit stream coding, like
+   * NRZI, Manchester, etc should be done prior this block.
+   *
+   * @param variant the framing variant
+   *
+   * @param preamble the preamble should be a repeated word. Note that due to AGC
+   * settling, the receiver may not receive the whole preamble. If the preamble
+   * is indeed a repeated pattern, a portion of it can be given as parameter.
+   * The block should be able to deal with this. However, a quite small subset
+   * may lead to a larger number of false alarms.
+   *
+   * @param preamble_threshold the maximum number of bits that are
+   * allowed to be wrong at the preamble
+   *
+   * @param sync the sysnchronization work following the preamble
+   *
+   * @param sync_threshold the maximum number of bits that are
+   * allowed to be wrong at the synchronization word
+
+   * @param frame_size_field_len the length of the field describing the frame
+   * length. I most cases should be 1 or 2.
+   *
+   * @param frame_len if the variant dictates a constant frame length, this
+   * parameter provides the length of the frame
+   *
+   * @param crc the CRC scheme to use
+   * @param descrambler the descramble used
+   * @param max_frame_len the maximum allowed frame length
+   * @return a shared pointer of a frame_acquisition block
+   */
   static sptr
   make(variant_t variant,
        const std::vector<uint8_t>& preamble,