From aea83c80c6f69f4c303261e1e0d2a0ba89a1ecb2 Mon Sep 17 00:00:00 2001
From: Tom Rondeau <trondeau@vt.edu>
Date: Sun, 9 Oct 2011 16:40:02 -0400
Subject: digital: updating documentation; adding everything to group 'digital'

---
 gr-digital/include/digital_constellation.h | 106 ++++++++++++++++++++++-------
 1 file changed, 80 insertions(+), 26 deletions(-)

(limited to 'gr-digital/include/digital_constellation.h')

diff --git a/gr-digital/include/digital_constellation.h b/gr-digital/include/digital_constellation.h
index 84f4814dfb..b6da7ff9ba 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:
-- 
cgit v1.2.3