digital: updating documentation; adding everything to group 'digital'

16 files changed, 122 insertions, 47 deletions

diff --git a/gr-digital/include/digital_binary_slicer_fb.h b/gr-digital/include/digital_binary_slicer_fb.h
index 2d10484db..4e6717de6 100644
--- a/gr-digital/include/digital_binary_slicer_fb.h
+++ b/gr-digital/include/digital_binary_slicer_fb.h
@@ -33,6 +33,7 @@ digital_binary_slicer_fb_sptr digital_make_binary_slicer_fb ();
 /*!
  * \brief slice float binary symbol outputting 1 bit output
  * \ingroup converter_blk
+ * \ingroup digital
  *
  * x <  0 --> 0
  * x >= 0 --> 1
diff --git a/gr-digital/include/digital_clock_recovery_mm_cc.h b/gr-digital/include/digital_clock_recovery_mm_cc.h
index 422bf811c..023891a66 100644
--- a/gr-digital/include/digital_clock_recovery_mm_cc.h
+++ b/gr-digital/include/digital_clock_recovery_mm_cc.h
@@ -41,6 +41,7 @@ digital_make_clock_recovery_mm_cc (float omega, float gain_omega,
 /*!
  * \brief Mueller and Müller (M&M) based clock recovery block with complex input, complex output.
  * \ingroup sync_blk
+ * \ingroup digital
  *
  * This implements the Mueller and Müller (M&M) discrete-time error-tracking synchronizer.
  * The complex version here is based on:
diff --git a/gr-digital/include/digital_clock_recovery_mm_ff.h b/gr-digital/include/digital_clock_recovery_mm_ff.h
index 6fc5ac261..5a2206fb2 100644
--- a/gr-digital/include/digital_clock_recovery_mm_ff.h
+++ b/gr-digital/include/digital_clock_recovery_mm_ff.h
@@ -41,6 +41,7 @@ digital_make_clock_recovery_mm_ff (float omega, float gain_omega,
 /*!
  * \brief Mueller and Müller (M&M) based clock recovery block with float input, float output.
  * \ingroup sync_blk
+ * \ingroup digital
  *
  * This implements the Mueller and Müller (M&M) discrete-time error-tracking synchronizer.
  *
diff --git a/gr-digital/include/digital_cma_equalizer_cc.h b/gr-digital/include/digital_cma_equalizer_cc.h
index 0dd99debd..93771dca4 100644
--- a/gr-digital/include/digital_cma_equalizer_cc.h
+++ b/gr-digital/include/digital_cma_equalizer_cc.h
@@ -36,6 +36,7 @@ digital_make_cma_equalizer_cc(int num_taps, float modulus, float mu, int sps);
 /*!
  * \brief Implements constant modulus adaptive filter on complex stream
  * \ingroup eq_blk
+ * \ingroup digital
  *
  * The error value and tap update equations (for p=2) can be found in:
  *
diff --git a/gr-digital/include/digital_constellation.h b/gr-digital/include/digital_constellation.h
index 84f4814df..b6da7ff9b 100644
--- a/gr-digital/include/digital_constellation.h
+++ b/gr-digital/include/digital_constellation.h
@@ -38,6 +38,21 @@
 class digital_constellation;
 typedef boost::shared_ptr<digital_constellation> digital_constellation_sptr;
 
+/*!
+ * \brief An abstracted constellation object
+ * \ingroup digital
+ *
+ * The constellation objects hold the necessary information to pass
+ * around constellation information for modulators and
+ * demodulators. These objects contain the mapping between the bits
+ * and the constellation points used to represent them as well as
+ * methods for slicing the symbol space. Various implementations are
+ * possible for efficiency and ease of use.
+ *
+ * Standard constellations (BPSK, QPSK, QAM, etc) can be inherited
+ * from this class and overloaded to perform optimized slicing and
+ * constellation mappings.
+ */
 class digital_constellation : public boost::enable_shared_from_this<digital_constellation>
 {
 public:
@@ -111,11 +126,8 @@ public:
 };
 
 /************************************************************/
-/* digital_constellation_calcdist                                */
+/* digital_constellation_calcdist                           */
 /*                                                          */
-/* Constellation which calculates the distance to each      */
-/* point in the constellation for decision making.          */
-/* Inefficient for large constellations.                    */
 /************************************************************/
 
 class digital_constellation_calcdist;
@@ -129,6 +141,13 @@ digital_make_constellation_calcdist (std::vector<gr_complex> constellation,
 				     unsigned int dimensionality);
 
 
+/*! \brief Calculate Euclidian distance for any constellation
+ *  \ingroup digital
+ *
+ * Constellation which calculates the distance to each point in the
+ * constellation for decision making. Inefficient for large
+ * constellations.
+ */
 class digital_constellation_calcdist : public digital_constellation
 {
  public:
@@ -146,15 +165,19 @@ class digital_constellation_calcdist : public digital_constellation
   digital_make_constellation_calcdist (std::vector<gr_complex> constellation);
 };
 
+
 /************************************************************/
-/* digital_constellation_sector                             */
-/*                                                          */
-/* An abstract class.                                       */
-/* Constellation space is divided into sectors.             */
-/* Each sector is associated with the nearest constellation */
-/* point.                                                   */
+/*! digital_constellation_sector                             */
 /************************************************************/
 
+/*!
+ * \brief Sectorized digital constellation
+ * \ingroup digital
+ *
+ * Constellation space is divided into sectors. Each sector is
+ * associated with the nearest constellation point.
+ *
+ */
 class digital_constellation_sector : public digital_constellation
 {
  public:
@@ -183,17 +206,23 @@ class digital_constellation_sector : public digital_constellation
 
 /************************************************************/
 /* digital_constellation_rect                               */
-/*                                                          */
-/* Only implemented for 1-(complex)dimensional              */
-/* constellation.                                           */
-/* Constellation space is divided into rectangular sectors. */
-/* Each sector is associated with the nearest constellation */
-/* point.                                                   */
-/* Works well for square QAM.                               */
-/* Works for any generic constellation provided sectors are */
-/* not too large.                                           */
 /************************************************************/
 
+/*!
+ * \brief Rectangular digital constellation
+ * \ingroup digital
+ *
+ * Only implemented for 1-(complex)dimensional constellation.
+ *
+ * Constellation space is divided into rectangular sectors. Each
+ * sector is associated with the nearest constellation point.
+ *
+ * Works well for square QAM.
+ *
+ * Works for any generic constellation provided sectors are not too
+ * large.
+ */
+
 class digital_constellation_rect;
 typedef boost::shared_ptr<digital_constellation_rect> digital_constellation_rect_sptr;
 
@@ -243,14 +272,9 @@ class digital_constellation_rect : public digital_constellation_sector
   
 };
 
+
 /************************************************************/
 /* digital_constellation_psk                                */
-/*                                                          */
-/* Constellation space is divided into pie slices sectors.  */
-/* Each slice is associated with the nearest constellation  */
-/* point.                                                   */
-/* Works well for PSK but nothing else.                     */
-/* Assumes that there is a constellation point at 1.        */
 /************************************************************/
 
 class digital_constellation_psk;
@@ -262,6 +286,18 @@ digital_make_constellation_psk (std::vector<gr_complex> constellation,
 				std::vector<unsigned int> pre_diff_code,
 				unsigned int n_sectors);
 
+/*! 
+ * \brief digital_constellation_psk
+ * \ingroup digital
+ *
+ * Constellation space is divided into pie slices sectors.
+ *
+ * Each slice is associated with the nearest constellation point. 
+ *
+ * Works well for PSK but nothing else.  
+ *
+ * Assumes that there is a constellation point at 1.x 
+ */
 class digital_constellation_psk : public digital_constellation_sector
 {
  public:
@@ -285,6 +321,7 @@ class digital_constellation_psk : public digital_constellation_sector
   
 };
 
+
 /************************************************************/
 /* digital_constellation_bpsk                               */
 /*                                                          */
@@ -299,6 +336,10 @@ typedef boost::shared_ptr<digital_constellation_bpsk> digital_constellation_bpsk
 digital_constellation_bpsk_sptr 
 digital_make_constellation_bpsk ();
 
+/*! 
+ * \brief Digital constellation for BPSK 
+ * \ingroup digital
+ */
 class digital_constellation_bpsk : public digital_constellation
 {
  public:
@@ -311,6 +352,7 @@ class digital_constellation_bpsk : public digital_constellation
   
 };
 
+
 /************************************************************/
 /* digital_constellation_qpsk                               */
 /*                                                          */
@@ -325,6 +367,10 @@ typedef boost::shared_ptr<digital_constellation_qpsk> digital_constellation_qpsk
 digital_constellation_qpsk_sptr 
 digital_make_constellation_qpsk ();
 
+/*! 
+ * \brief Digital constellation for QPSK
+ * \ingroup digital
+ */
 class digital_constellation_qpsk : public digital_constellation
 {
  public:
@@ -337,6 +383,7 @@ class digital_constellation_qpsk : public digital_constellation
   
 };
 
+
 /************************************************************/
 /* digital_constellation_dqpsk                              */
 /*                                                          */
@@ -344,7 +391,6 @@ class digital_constellation_qpsk : public digital_constellation
 /*                                                          */
 /************************************************************/
 
-//! \brief DQPSK-specific constellation and decision maker
 class digital_constellation_dqpsk;
 typedef boost::shared_ptr<digital_constellation_dqpsk> digital_constellation_dqpsk_sptr;
 
@@ -352,6 +398,10 @@ typedef boost::shared_ptr<digital_constellation_dqpsk> digital_constellation_dqp
 digital_constellation_dqpsk_sptr 
 digital_make_constellation_dqpsk ();
 
+/*!
+ * \brief Digital constellation for DQPSK
+ * \ingroup digital
+ */
 class digital_constellation_dqpsk : public digital_constellation
 {
  public:
@@ -379,6 +429,10 @@ typedef boost::shared_ptr<digital_constellation_8psk> digital_constellation_8psk
 digital_constellation_8psk_sptr 
 digital_make_constellation_8psk ();
 
+/*! 
+ * \brief Digital constellation for 8PSK
+ * \ingroup digital
+ */
 class digital_constellation_8psk : public digital_constellation
 {
  public:
diff --git a/gr-digital/include/digital_constellation_decoder_cb.h b/gr-digital/include/digital_constellation_decoder_cb.h
index 022456733..d587f6bc4 100644
--- a/gr-digital/include/digital_constellation_decoder_cb.h
+++ b/gr-digital/include/digital_constellation_decoder_cb.h
@@ -36,6 +36,7 @@ digital_make_constellation_decoder_cb (digital_constellation_sptr constellation)
 /*!
  * \brief Constellation Decoder
  * \ingroup coding_blk
+ * \ingroup digital
  *
  */
 class digital_constellation_decoder_cb : public gr_block
diff --git a/gr-digital/include/digital_constellation_receiver_cb.h b/gr-digital/include/digital_constellation_receiver_cb.h
index 0ac80450f..a67f67082 100644
--- a/gr-digital/include/digital_constellation_receiver_cb.h
+++ b/gr-digital/include/digital_constellation_receiver_cb.h
@@ -39,28 +39,36 @@ digital_make_constellation_receiver_cb (digital_constellation_sptr constellation
 					float loop_bw, float fmin, float fmax);
 
 /*!
- * \brief This block takes care of receiving generic modulated signals through phase, frequency, and symbol
- * synchronization. 
+ * \brief This block takes care of receiving generic modulated signals
+ * through phase, frequency, and symbol synchronization.
  * \ingroup sync_blk
  * \ingroup demod_blk
+ * \ingroup digital
  *
- * This block takes care of receiving generic modulated signals through phase, frequency, and symbol
- * synchronization. It performs carrier frequency and phase locking as well as symbol timing recovery. 
+ * This block takes care of receiving generic modulated signals
+ * through phase, frequency, and symbol synchronization. It performs
+ * carrier frequency and phase locking as well as symbol timing
+ * recovery.
  *
- * The phase and frequency synchronization are based on a Costas loop that finds the error of the incoming
- * signal point compared to its nearest constellation point. The frequency and phase of the NCO are 
+ * The phase and frequency synchronization are based on a Costas loop
+ * that finds the error of the incoming signal point compared to its
+ * nearest constellation point. The frequency and phase of the NCO are
  * updated according to this error.
  *
- * The symbol synchronization is done using a modified Mueller and Muller circuit from the paper:
+ * The symbol synchronization is done using a modified Mueller and
+ * Muller circuit from the paper:
  * 
- *    G. R. Danesfahani, T.G. Jeans, "Optimisation of modified Mueller and Muller 
- *    algorithm,"  Electronics Letters, Vol. 31, no. 13,  22 June 1995, pp. 1032 - 1033.
+ *    G. R. Danesfahani, T.G. Jeans, "Optimisation of modified Mueller
+ *    and Muller algorithm," Electronics Letters, Vol. 31, no. 13, 22
+ *    June 1995, pp. 1032 - 1033.
  *
- * This circuit interpolates the downconverted sample (using the NCO developed by the Costas loop)
- * every mu samples, then it finds the sampling error based on this and the past symbols and the decision
- * made on the samples. Like the phase error detector, there are optimized decision algorithms for BPSK
- * and QPKS, but 8PSK uses another brute force computation against all possible symbols. The modifications
- * to the M&M used here reduce self-noise.
+ * This circuit interpolates the downconverted sample (using the NCO
+ * developed by the Costas loop) every mu samples, then it finds the
+ * sampling error based on this and the past symbols and the decision
+ * made on the samples. Like the phase error detector, there are
+ * optimized decision algorithms for BPSK and QPKS, but 8PSK uses
+ * another brute force computation against all possible symbols. The
+ * modifications to the M&M used here reduce self-noise.
  *
  */
 
@@ -78,8 +86,7 @@ protected:
    * \brief Constructor to synchronize incoming M-PSK symbols
    *
    * \param constellation	constellation of points for generic modulation
-   * \param alpha	gain parameter to adjust the phase in the Costas loop (~0.01)
-   * \param beta        gain parameter to adjust the frequency in the Costas loop (~alpha^2/4)	
+   * \param loop_bw	Loop bandwidth of the Costas Loop (~ 2pi/100)
    * \param fmin        minimum normalized frequency value the loop can achieve
    * \param fmax        maximum normalized frequency value the loop can achieve
    *
diff --git a/gr-digital/include/digital_correlate_access_code_bb.h b/gr-digital/include/digital_correlate_access_code_bb.h
index 2607ae84c..c21875f0e 100644
--- a/gr-digital/include/digital_correlate_access_code_bb.h
+++ b/gr-digital/include/digital_correlate_access_code_bb.h
@@ -39,6 +39,7 @@ digital_make_correlate_access_code_bb (const std::string &access_code, int thres
 /*!
  * \brief Examine input for specified access code, one bit at a time.
  * \ingroup sync_blk
+ * \ingroup digital
  *
  * input:  stream of bits, 1 bit per input byte (data in LSB)
  * output: stream of bits, 2 bits per output byte (data in LSB, flag in next higher bit)
diff --git a/gr-digital/include/digital_costas_loop_cc.h b/gr-digital/include/digital_costas_loop_cc.h
index 7b2cd6dad..3811825dd 100644
--- a/gr-digital/include/digital_costas_loop_cc.h
+++ b/gr-digital/include/digital_costas_loop_cc.h
@@ -30,8 +30,10 @@
 #include <fstream>
 
 
-/*! \brief A Costas loop carrier recovery module.
+/*! 
+ * \brief A Costas loop carrier recovery module.
  * \ingroup sync_blk
+ * \ingroup digital
  *  
  *  The Costas loop locks to the center frequency of a signal and
  *  downconverts it to baseband. The second (order=2) order loop is
@@ -42,9 +44,9 @@
  *
  *  More details can be found online:
  *
- *  J. Feigin, "Practical Costas loop design: Designing a simple and inexpensive
- *  BPSK Costas loop carrier recovery circuit," RF signal processing, pp. 20-36,
- *  2002.
+ *  J. Feigin, "Practical Costas loop design: Designing a simple and
+ *  inexpensive BPSK Costas loop carrier recovery circuit," RF signal
+ *  processing, pp. 20-36, 2002.
  *
  *  http://rfdesign.com/images/archive/0102Feigin20.pdf
  *  
diff --git a/gr-digital/include/digital_cpmmod_bc.h b/gr-digital/include/digital_cpmmod_bc.h
index 6212fc777..85b901ba2 100644
--- a/gr-digital/include/digital_cpmmod_bc.h
+++ b/gr-digital/include/digital_cpmmod_bc.h
@@ -43,6 +43,7 @@ digital_make_cpmmod_bc(int type, float h,
  * \brief Generic CPM modulator
  *
  * \ingroup modulation_blk
+ * \ingroup digital
  *
  * \param type The modulation type. Can be one of LREC, LRC, LSRC, TFM
  *             or GAUSSIAN. See gr_cpm::phase_response() for a
diff --git a/gr-digital/include/digital_crc32.h b/gr-digital/include/digital_crc32.h
index 64aa12f7b..869cf7f45 100644
--- a/gr-digital/include/digital_crc32.h
+++ b/gr-digital/include/digital_crc32.h
@@ -28,7 +28,7 @@
 
 /*!
  * \brief update running CRC-32
- * \ingroup misc
+ * \ingroup digital
  *
  * Update a running CRC with the bytes buf[0..len-1] The CRC should be
  * initialized to all 1's, and the transmitted value is the 1's
diff --git a/gr-digital/include/digital_fll_band_edge_cc.h b/gr-digital/include/digital_fll_band_edge_cc.h
index 4fa7b3a3e..576dfab87 100644
--- a/gr-digital/include/digital_fll_band_edge_cc.h
+++ b/gr-digital/include/digital_fll_band_edge_cc.h
@@ -39,6 +39,7 @@ digital_fll_band_edge_cc_sptr digital_make_fll_band_edge_cc (float samps_per_sym
  * \brief Frequency Lock Loop using band-edge filters
  *
  * \ingroup general
+ * \ingroup digital
  *
  * The frequency lock loop derives a band-edge filter that covers the
  * upper and lower bandwidths of a digitally-modulated signal. The
diff --git a/gr-digital/include/digital_gmskmod_bc.h b/gr-digital/include/digital_gmskmod_bc.h
index 92b53cd4b..4b0952401 100644
--- a/gr-digital/include/digital_gmskmod_bc.h
+++ b/gr-digital/include/digital_gmskmod_bc.h
@@ -37,6 +37,7 @@ digital_make_gmskmod_bc(unsigned samples_per_sym=2,
  * \brief GMSK modulator
  *
  * \ingroup modulation_blk
+ * \ingroup digital
  *
  * \param samples_per_sym Samples per symbol.
  * \param bt The 3 dB time-bandwidth product.
diff --git a/gr-digital/include/digital_kurtotic_equalizer_cc.h b/gr-digital/include/digital_kurtotic_equalizer_cc.h
index e01cbd6e6..018a906b0 100644
--- a/gr-digital/include/digital_kurtotic_equalizer_cc.h
+++ b/gr-digital/include/digital_kurtotic_equalizer_cc.h
@@ -36,6 +36,7 @@ digital_make_kurtotic_equalizer_cc(int num_taps, float mu);
 /*!
  * \brief Implements a kurtosis-based adaptive equalizer on complex stream
  * \ingroup eq_blk
+ * \ingroup digital
  *
  * Y. Guo, J. Zhao, Y. Sun, "Sign kurtosis maximization based blind
  * equalization algorithm," IEEE Conf. on Control, Automation,
diff --git a/gr-digital/include/digital_lms_dd_equalizer_cc.h b/gr-digital/include/digital_lms_dd_equalizer_cc.h
index e3ad4bf4a..050d8781d 100644
--- a/gr-digital/include/digital_lms_dd_equalizer_cc.h
+++ b/gr-digital/include/digital_lms_dd_equalizer_cc.h
@@ -36,6 +36,7 @@ digital_lms_dd_equalizer_cc_sptr digital_make_lms_dd_equalizer_cc (int num_taps,
 /*!
  * \brief Least-Mean-Square Decision Directed Equalizer (complex in/out)
  * \ingroup eq_blk
+ * \ingroup digital
  *
  * This block implements an LMS-based decision-directed equalizer.
  * It uses a set of weights, w, to correlate against the inputs, u,
diff --git a/gr-digital/include/digital_mpsk_receiver_cc.h b/gr-digital/include/digital_mpsk_receiver_cc.h
index f8aa4e341..74aca5649 100644
--- a/gr-digital/include/digital_mpsk_receiver_cc.h
+++ b/gr-digital/include/digital_mpsk_receiver_cc.h
@@ -47,6 +47,7 @@ digital_make_mpsk_receiver_cc (unsigned int M, float theta,
  * through phase, frequency, and symbol synchronization.
  * \ingroup sync_blk
  * \ingroup demod_blk
+ * \ingroup digital
  *
  * This block takes care of receiving M-PSK modulated signals through
  * phase, frequency, and symbol synchronization. It performs carrier