analog: added some documentation for a number of blocks.

author: Tom Rondeau <trondeau@vt.edu> 2013-03-13 23:03:15 -0400
committer: Tom Rondeau <trondeau@vt.edu> 2013-03-13 23:03:15 -0400
commit: 3e7d338c626a94b9073db3c57b90ab5d9f35b7f4 (patch)
tree: 405a248bcdb0ecc781d55334239aaa0b2317cdb9
parent: 9616494c07b86b8b76c3c49c66fe9dfa037989e7 (diff)
15 files changed, 139 insertions, 24 deletions
diff --git a/gr-analog/include/analog/agc.h b/gr-analog/include/analog/agc.h
index 92d777fa19..c304ba8f3e 100644
--- a/gr-analog/include/analog/agc.h
+++ b/gr-analog/include/analog/agc.h
@@ -39,6 +39,14 @@ namespace gr {
       class ANALOG_API agc_cc
       {
       public:
+        /*!
+         * Construct a complex value AGC loop implementation object.
+         *
+         * \param rate the update rate of the loop.
+         * \param reference reference value to adjust signal power to.
+         * \param gain initial gain value.
+         * \param max_gain maximum gain value (0 for unlimited).
+         */
 	agc_cc(float rate = 1e-4, float reference = 1.0,
 	       float gain = 1.0, float max_gain = 0.0)
 	  : _rate(rate), _reference(reference),
@@ -90,6 +98,14 @@ namespace gr {
       class ANALOG_API agc_ff 
       {
       public:
+        /*!
+         * Construct a floating point value AGC loop implementation object.
+         *
+         * \param rate the update rate of the loop.
+         * \param reference reference value to adjust signal power to.
+         * \param gain initial gain value.
+         * \param max_gain maximum gain value (0 for unlimited).
+         */
 	agc_ff(float rate = 1e-4, float reference = 1.0,
 	       float gain = 1.0, float max_gain = 0.0)
 	  : _rate(rate), _reference(reference), _gain(gain),
diff --git a/gr-analog/include/analog/agc2.h b/gr-analog/include/analog/agc2.h
index 75a203e9fc..8d1958d293 100644
--- a/gr-analog/include/analog/agc2.h
+++ b/gr-analog/include/analog/agc2.h
@@ -39,6 +39,15 @@ namespace gr {
       class ANALOG_API agc2_cc
       {
       public:
+        /*!
+         * Construct a comple value AGC loop implementation object.
+         *
+         * \param attack_rate the update rate of the loop when in attack mode.
+         * \param decay_rate the update rate of the loop when in decay mode.
+         * \param reference reference value to adjust signal power to.
+         * \param gain initial gain value.
+         * \param max_gain maximum gain value (0 for unlimited).
+         */
 	agc2_cc(float attack_rate = 1e-1, float decay_rate = 1e-2,
 		float reference = 1.0,
 		float gain = 1.0, float max_gain = 0.0)
@@ -99,6 +108,15 @@ namespace gr {
       class ANALOG_API agc2_ff
       {
       public:
+        /*!
+         * Construct a floating point value AGC loop implementation object.
+         *
+         * \param attack_rate the update rate of the loop when in attack mode.
+         * \param decay_rate the update rate of the loop when in decay mode.
+         * \param reference reference value to adjust signal power to.
+         * \param gain initial gain value.
+         * \param max_gain maximum gain value (0 for unlimited).
+         */
 	agc2_ff(float attack_rate = 1e-1, float decay_rate = 1e-2,
 		float reference = 1.0,
 		float gain = 1.0, float max_gain = 0.0)
diff --git a/gr-analog/include/analog/agc2_cc.h b/gr-analog/include/analog/agc2_cc.h
index c922ccd4da..7f3a7c24bd 100644
--- a/gr-analog/include/analog/agc2_cc.h
+++ b/gr-analog/include/analog/agc2_cc.h
@@ -31,7 +31,8 @@ namespace gr {
   namespace analog {
 
     /*!
-     * \brief high performance Automatic Gain Control class
+     * \brief high performance Automatic Gain Control class with
+     * attack and decay rates.
      * \ingroup level_blk
      *
      * For Power the absolute value of the complex number is used.
@@ -42,6 +43,15 @@ namespace gr {
       // gr::analog::agc2_cc::sptr
       typedef boost::shared_ptr<agc2_cc> sptr;
             
+      /*!
+       * Build a complex value AGC loop block with attack and decay rates.
+       *
+       * \param attack_rate the update rate of the loop when in attack mode.
+       * \param decay_rate the update rate of the loop when in decay mode.
+       * \param reference reference value to adjust signal power to.
+       * \param gain initial gain value.
+       * \param max_gain maximum gain value (0 for unlimited).
+       */
       static sptr make(float attack_rate = 1e-1, float decay_rate = 1e-2,
 		       float reference = 1.0,
 		       float gain = 1.0, float max_gain = 0.0);
diff --git a/gr-analog/include/analog/agc2_ff.h b/gr-analog/include/analog/agc2_ff.h
index 27dd6d92e5..4bb7b0f646 100644
--- a/gr-analog/include/analog/agc2_ff.h
+++ b/gr-analog/include/analog/agc2_ff.h
@@ -31,7 +31,8 @@ namespace gr {
   namespace analog {
 
     /*!
-     * \brief high performance Automatic Gain Control class
+     * \brief high performance Automatic Gain Control class with
+     * attack and decay rates.
      *
      * \ingroup level_blk
      * Power is approximated by absolute value
@@ -42,6 +43,15 @@ namespace gr {
       // gr::analog::agc2_ff::sptr
       typedef boost::shared_ptr<agc2_ff> sptr;
             
+      /*!
+       * Build a floating point AGC loop block with attack and decay rates.
+       *
+       * \param attack_rate the update rate of the loop when in attack mode.
+       * \param decay_rate the update rate of the loop when in decay mode.
+       * \param reference reference value to adjust signal power to.
+       * \param gain initial gain value.
+       * \param max_gain maximum gain value (0 for unlimited).
+       */
       static sptr make(float attack_rate = 1e-1, float decay_rate = 1e-2,
 		       float reference = 1.0,
 		       float gain = 1.0, float max_gain = 0.0);
diff --git a/gr-analog/include/analog/agc_cc.h b/gr-analog/include/analog/agc_cc.h
index b2b1a9b430..0e59f8593b 100644
--- a/gr-analog/include/analog/agc_cc.h
+++ b/gr-analog/include/analog/agc_cc.h
@@ -42,6 +42,14 @@ namespace gr {
       // gr::analog::agc_cc::sptr
       typedef boost::shared_ptr<agc_cc> sptr;
             
+      /*!
+       * Build a complex value AGC loop block.
+       *
+       * \param rate the update rate of the loop.
+       * \param reference reference value to adjust signal power to.
+       * \param gain initial gain value.
+       * \param max_gain maximum gain value (0 for unlimited).
+       */
       static sptr make(float rate = 1e-4, float reference = 1.0,
 		       float gain = 1.0, float max_gain = 0.0);
 
diff --git a/gr-analog/include/analog/agc_ff.h b/gr-analog/include/analog/agc_ff.h
index 30d1ae1fd9..6046d6f645 100644
--- a/gr-analog/include/analog/agc_ff.h
+++ b/gr-analog/include/analog/agc_ff.h
@@ -42,6 +42,14 @@ namespace gr {
       // gr::analog::agc_ff::sptr
       typedef boost::shared_ptr<agc_ff> sptr;
             
+      /*!
+       * Build a floating point AGC loop block.
+       *
+       * \param rate the update rate of the loop.
+       * \param reference reference value to adjust signal power to.
+       * \param gain initial gain value.
+       * \param max_gain maximum gain value (0 for unlimited).
+       */
       static sptr make(float rate = 1e-4, float reference = 1.0,
 		       float gain = 1.0, float max_gain = 0.0);
       
diff --git a/gr-analog/include/analog/cpm.h b/gr-analog/include/analog/cpm.h
index d22e02321c..aff0dd19eb 100644
--- a/gr-analog/include/analog/cpm.h
+++ b/gr-analog/include/analog/cpm.h
@@ -28,6 +28,9 @@
 namespace gr {
   namespace analog {
 
+    /*! \brief Return the taps for an interpolating FIR filter
+     *   (gr::filter::interp_fir_filter_fff).
+     */
     class ANALOG_API cpm
     {
     public:
@@ -40,25 +43,30 @@ namespace gr {
 	GENERIC = 999
       };
       
-      /*! \brief Return the taps for an interpolating FIR filter (gr_interp_fir_filter_fff).
+      /*! \brief Return the taps for an interpolating FIR filter
+       *   (gr::filter::interp_fir_filter_fff).
        *
-       * These taps represent the phase response \f$g(k)\f$ for use in a CPM modulator,
-       * see also gr_cpmmod_bc.
+       * These taps represent the phase response \f$g(k)\f$ for use in
+       * a CPM modulator, see also gr_cpmmod_bc.
        *
-       * \param type The CPM type (Rectangular, Raised Cosine, Spectral Raised Cosine,
-       *             Tamed FM or Gaussian).
+       * \param type The CPM type (Rectangular, Raised Cosine,
+       *             Spectral Raised Cosine, Tamed FM or Gaussian).
        * \param samples_per_sym Samples per symbol.
        * \param L The length of the phase response in symbols.
-       * \param beta For Spectral Raised Cosine, this is the rolloff factor. For Gaussian
-       *             phase responses, this the 3dB-time-bandwidth product. For all other
-       *             cases, it is ignored.
+       * \param beta For Spectral Raised Cosine, this is the rolloff
+       *             factor. For Gaussian phase responses, this the
+       *             3dB-time-bandwidth product. For all other cases,
+       *             it is ignored.
        *
-       * Output: returns a vector of length \a K = \p samples_per_sym x \p L.
-       *         This can be used directly in an interpolating FIR filter such as
-       *         gr_interp_fir_filter_fff with interpolation factor \p samples_per_sym.
+       * Output: returns a vector of length \a K = \p samples_per_sym
+       *         x \p L.  This can be used directly in an
+       *         interpolating FIR filter such as
+       *         gr_interp_fir_filter_fff with interpolation factor \p
+       *         samples_per_sym.
        *
-       * All phase responses are normalised s.t. \f$ \sum_{k=0}^{K-1} g(k) = 1\f$; this will cause
-       * a maximum phase change of \f$ h \cdot \pi\f$ between two symbols, where \a h is the
+       * All phase responses are normalised s.t. \f$ \sum_{k=0}^{K-1}
+       * g(k) = 1\f$; this will cause a maximum phase change of \f$ h
+       * \cdot \pi\f$ between two symbols, where \a h is the
        * modulation index.
        *
        * The following phase responses can be generated:
@@ -77,7 +85,8 @@ namespace gr {
        * [1]: Anderson, Aulin and Sundberg; Digital Phase Modulation
        */
       static std::vector<float>
-	phase_response(cpm_type type, unsigned samples_per_sym, unsigned L, double beta=0.3);
+	phase_response(cpm_type type, unsigned samples_per_sym,
+                       unsigned L, double beta=0.3);
     };
   } // namespace analog
 } // namespace gr
diff --git a/gr-analog/include/analog/ctcss_squelch_ff.h b/gr-analog/include/analog/ctcss_squelch_ff.h
index f880299173..b63876714d 100644
--- a/gr-analog/include/analog/ctcss_squelch_ff.h
+++ b/gr-analog/include/analog/ctcss_squelch_ff.h
@@ -31,7 +31,7 @@ namespace gr {
   namespace analog {
 
     /*!
-     * \brief gate or zero output if ctcss tone not present
+     * \brief gate or zero output if CTCSS tone not present
      * \ingroup level_blk
      */
     class ANALOG_API ctcss_squelch_ff :
@@ -47,6 +47,14 @@ namespace gr {
       
       /*!
        * \brief Make CTCSS tone squelch block.
+       *
+       * \param rate gain of the internal frequency filters.
+       * \param freq frequency value to use as the squelch tone.
+       * \param level threshold level for the squelch tone.
+       * \param len length of the frequency filters.
+       * \param ramp sets response characteristic.
+       * \param gate if true, no output if no squelch tone.
+       *             if false, output 0's if no squelch tone.
        */
       static sptr make(int rate, float freq, float level,
 		       int len, int ramp, bool gate);
diff --git a/gr-analog/include/analog/feedforward_agc_cc.h b/gr-analog/include/analog/feedforward_agc_cc.h
index 9e259a4eba..743b9b3a3b 100644
--- a/gr-analog/include/analog/feedforward_agc_cc.h
+++ b/gr-analog/include/analog/feedforward_agc_cc.h
@@ -30,7 +30,8 @@ namespace gr {
   namespace analog {
 
     /*!
-     * \brief Non-causal AGC which computes required gain based on max absolute value over nsamples
+     * \brief Non-causal AGC which computes required gain based on max
+     * absolute value over nsamples
      * \ingroup level_blk
      */
     class ANALOG_API feedforward_agc_cc : virtual public gr_sync_block
@@ -38,7 +39,13 @@ namespace gr {
     public:
       // gr::analog::feedforward_agc_cc::sptr
       typedef boost::shared_ptr<feedforward_agc_cc> sptr;
-      
+
+      /*!
+       * Build a complex valued feed-forward AGC loop block.
+       *
+       * \param nsamples number of samples to look ahead.
+       * \param reference reference value to adjust signal power to.
+       */
       static sptr make(int nsamples, float reference);
     };
     
diff --git a/gr-analog/include/analog/frequency_modulator_fc.h b/gr-analog/include/analog/frequency_modulator_fc.h
index 8706d513a6..67be1ff00e 100644
--- a/gr-analog/include/analog/frequency_modulator_fc.h
+++ b/gr-analog/include/analog/frequency_modulator_fc.h
@@ -41,6 +41,11 @@ namespace gr {
       // gr::analog::frequency_modulator_fc::sptr
       typedef boost::shared_ptr<frequency_modulator_fc> sptr;
 
+      /*!
+       * Build a frequency modulator block.
+       *
+       * \param sensitivity radians/sample = amplitude * sensitivity
+       */
       static sptr make(double sensitivity);
 
       virtual void set_sensitivity(float sens) = 0;
diff --git a/gr-analog/include/analog/pwr_squelch_cc.h b/gr-analog/include/analog/pwr_squelch_cc.h
index 79364a86b5..e3f6fb67fc 100644
--- a/gr-analog/include/analog/pwr_squelch_cc.h
+++ b/gr-analog/include/analog/pwr_squelch_cc.h
@@ -50,8 +50,9 @@ namespace gr {
        *
        * \param db threshold (in dB) for power squelch
        * \param alpha Gain of averaging filter
-       * \param ramp
-       * \param gate 
+       * \param ramp sets response characteristic.
+       * \param gate if true, no output if no squelch tone.
+       *             if false, output 0's if no squelch tone.
        */
       static sptr make(double db, double alpha=0.0001,
 		       int ramp=0, bool gate=false);
diff --git a/gr-analog/include/analog/pwr_squelch_ff.h b/gr-analog/include/analog/pwr_squelch_ff.h
index 6fdebec746..f8f7b4aac2 100644
--- a/gr-analog/include/analog/pwr_squelch_ff.h
+++ b/gr-analog/include/analog/pwr_squelch_ff.h
@@ -50,8 +50,9 @@ namespace gr {
        *
        * \param db threshold (in dB) for power squelch
        * \param alpha Gain of averaging filter
-       * \param ramp
-       * \param gate 
+       * \param ramp sets response characteristic.
+       * \param gate if true, no output if no squelch tone.
+       *             if false, output 0's if no squelch tone.
        */
       static sptr make(double db, double alpha=0.0001,
 		       int ramp=0, bool gate=false);
diff --git a/gr-analog/include/analog/quadrature_demod_cf.h b/gr-analog/include/analog/quadrature_demod_cf.h
index 916d8b2ece..fc29e494da 100644
--- a/gr-analog/include/analog/quadrature_demod_cf.h
+++ b/gr-analog/include/analog/quadrature_demod_cf.h
@@ -42,6 +42,12 @@ namespace gr {
       // gr::analog::quadrature_demod_cf::sptr
       typedef boost::shared_ptr<quadrature_demod_cf> sptr;
 
+      /* \brief Make a quadrature demodulator block.
+       *
+       * \param gain Gain setting to adjust the output amplitude. Set
+       *             based on converting the phase difference between
+       *             samples to a nominal output value.
+       */
       static sptr make(float gain);
 
       virtual void set_gain(float gain) = 0;
diff --git a/gr-analog/include/analog/rail_ff.h b/gr-analog/include/analog/rail_ff.h
index e51b2fc935..120ca2815b 100644
--- a/gr-analog/include/analog/rail_ff.h
+++ b/gr-analog/include/analog/rail_ff.h
@@ -39,6 +39,12 @@ namespace gr {
       // gr::analog::rail_ff::sptr
       typedef boost::shared_ptr<rail_ff> sptr;
 
+      /*!
+       * Build a rail block.
+       *
+       * \param lo the low value to clip to.
+       * \param hi the high value to clip to.
+       */
       static sptr make(float lo, float hi);
 
       virtual float lo() const = 0;
diff --git a/gr-analog/include/analog/sincos.h b/gr-analog/include/analog/sincos.h
index 38b9d96da0..a71164c885 100644
--- a/gr-analog/include/analog/sincos.h
+++ b/gr-analog/include/analog/sincos.h
@@ -28,8 +28,10 @@
 namespace gr {
   namespace analog {
 
-  // compute sine and cosine at the same time
+  //! compute double sine and cosine at the same time
   ANALOG_API void sincos(double x, double *sin, double *cos);
+
+  //! compute floating point sine and cosine at the same time
   ANALOG_API void sincosf(float x, float *sin, float *cos);
 
   } /* namespace analog */
author	Tom Rondeau <trondeau@vt.edu>	2013-03-13 23:03:15 -0400
committer	Tom Rondeau <trondeau@vt.edu>	2013-03-13 23:03:15 -0400
commit	3e7d338c626a94b9073db3c57b90ab5d9f35b7f4 (patch)
tree	405a248bcdb0ecc781d55334239aaa0b2317cdb9
parent	9616494c07b86b8b76c3c49c66fe9dfa037989e7 (diff)