Merge branch 'next' of http://gnuradio.org/git/gnuradio into next

Conflicts:
	gr-digital/include/digital_constellation.h

19 files changed, 141 insertions, 3 deletions

diff --git a/gr-audio/Makefile.am b/gr-audio/Makefile.am
index cde1702f2..da4106c23 100644
--- a/gr-audio/Makefile.am
+++ b/gr-audio/Makefile.am
@@ -21,7 +21,7 @@
 
 include $(top_srcdir)/Makefile.common
 
-SUBDIRS = include lib examples
+SUBDIRS = include lib examples doc
 
 if PYTHON
 SUBDIRS += grc swig
diff --git a/gr-audio/doc/.gitignore b/gr-audio/doc/.gitignore
new file mode 100644
index 000000000..b336cc7ce
--- /dev/null
+++ b/gr-audio/doc/.gitignore
@@ -0,0 +1,2 @@
+/Makefile
+/Makefile.in
diff --git a/gr-audio/doc/Makefile.am b/gr-audio/doc/Makefile.am
new file mode 100644
index 000000000..959a9044f
--- /dev/null
+++ b/gr-audio/doc/Makefile.am
@@ -0,0 +1,27 @@
+#
+# Copyright 2011 Free Software Foundation, Inc.
+# 
+# This file is part of GNU Radio
+# 
+# GNU Radio is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 3, or (at your option)
+# any later version.
+# 
+# GNU Radio is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+# 
+# You should have received a copy of the GNU General Public License
+# along with GNU Radio; see the file COPYING.  If not, write to
+# the Free Software Foundation, Inc., 51 Franklin Street,
+# Boston, MA 02110-1301, USA.
+# 
+
+include $(top_srcdir)/Makefile.common
+
+SUBDIRS =
+
+dist_gr_doc_DATA =		\
+	README.audio
diff --git a/gr-audio/doc/README.audio b/gr-audio/doc/README.audio
new file mode 100644
index 000000000..ebd0fe5d7
--- /dev/null
+++ b/gr-audio/doc/README.audio
@@ -0,0 +1,20 @@
+This is the gr-audio package. This package includes all of the
+supported audio interfaces, including:
+    - alsa
+    - oss
+    - jack
+    - portaudio
+    - osx
+    - windows
+
+Typically, the audio package will auto-detect the proper driver to use
+based on the system it is run on. Import this package with:
+
+    from gnuradio import audio
+
+See the Doxygen documentation for details about the blocks available
+in this package. A quick listing of the details can be found in Python
+after importing by using: 
+
+    help(audio)
+
diff --git a/gr-audio/doc/audio.dox b/gr-audio/doc/audio.dox
new file mode 100644
index 000000000..3a0cb5e48
--- /dev/null
+++ b/gr-audio/doc/audio.dox
@@ -0,0 +1,51 @@
+/*! \page page_audio Audio Interface
+
+\section Introduction
+
+This is the gr-audio package. This package includes all of the
+supported audio interfaces, including:
+
+\li alsa
+\li oss
+\li jack
+\li portaudio
+\li osx
+\li windows
+
+\code
+    from gnuradio import audio
+\endcode
+
+See the Doxygen documentation for details about the blocks available
+in this package. The relevant blocks are listed in the \ref audio_blk group.
+
+A quick listing of the details can be found in Python after importing
+by using:
+
+\code
+    help(digital)
+\endcode
+
+
+\section Usage
+For an audio source, a typical OptionParser option and it's use looks
+like:
+
+\code
+    parser.add_option("-O", "--audio-output", type="string", default="",
+                       help="pcm device name.  E.g., hw:0,0 or surround51 or /dev/dsp")
+    audio_rate = 32e3
+    audio_sink = audio.sink (int (audio_rate), options.audio_output)
+\endcode
+
+Similarly, an audio sink would have a typical OptionParser option and
+its use would look like:
+
+\code
+    parser.add_option("-I", "--audio-input", type="string", default="",
+                      help="pcm input device name.  E.g., hw:0,0 or /dev/dsp")
+    audio_rate = 32e3
+    audio_source = audio.source(int(audio_rate), audio_input)
+\endcode
+
+*/
diff --git a/gr-audio/include/gr_audio_sink.h b/gr-audio/include/gr_audio_sink.h
index ca3b15a37..ec064b64b 100644
--- a/gr-audio/include/gr_audio_sink.h
+++ b/gr-audio/include/gr_audio_sink.h
@@ -25,6 +25,19 @@
 #include <gr_audio_api.h>
 #include <gr_sync_block.h>
 
+/*!
+ * \brief Creates a sink from an audio device.
+ * \ingroup audio_blk
+ *
+ * Creates a sink from an audio device at a specified
+ * sample_rate. The specific audio device to use can be specified as
+ * the device_name parameter. Typical choices are:
+ * \li pulse
+ * \li hw:0,0
+ * \li plughw:0,0
+ * \li surround51
+ * \li /dev/dsp
+ */
 class GR_AUDIO_API audio_sink : virtual public gr_sync_block{
 public:
     typedef boost::shared_ptr<audio_sink> sptr;
diff --git a/gr-audio/include/gr_audio_source.h b/gr-audio/include/gr_audio_source.h
index b8ae2ca5f..eca22e3eb 100644
--- a/gr-audio/include/gr_audio_source.h
+++ b/gr-audio/include/gr_audio_source.h
@@ -25,6 +25,19 @@
 #include <gr_audio_api.h>
 #include <gr_sync_block.h>
 
+/*!
+ * \brief Creates a source from an audio device.
+ * \ingroup audio_blk
+ *
+ * Creates a source from an audio device at a specified
+ * sample_rate. The specific audio device to use can be specified as
+ * the device_name parameter. Typical choices are:
+ * \li pulse
+ * \li hw:0,0
+ * \li plughw:0,0
+ * \li surround51
+ * \li /dev/dsp
+ */
 class GR_AUDIO_API audio_source : virtual public gr_sync_block{
 public:
     typedef boost::shared_ptr<audio_source> sptr;
diff --git a/gr-audio/lib/alsa/audio_alsa_sink.h b/gr-audio/lib/alsa/audio_alsa_sink.h
index 23e406d6b..b33b84644 100644
--- a/gr-audio/lib/alsa/audio_alsa_sink.h
+++ b/gr-audio/lib/alsa/audio_alsa_sink.h
@@ -34,6 +34,7 @@
 
 /*!
  * \brief audio sink using ALSA
+ * \ingroup audio_blk
  *
  * The sink has N input streams of floats, where N depends
  * on the hardware characteristics of the selected device.
diff --git a/gr-audio/lib/alsa/audio_alsa_source.h b/gr-audio/lib/alsa/audio_alsa_source.h
index e38af3872..142ae711a 100644
--- a/gr-audio/lib/alsa/audio_alsa_source.h
+++ b/gr-audio/lib/alsa/audio_alsa_source.h
@@ -37,6 +37,7 @@ typedef boost::shared_ptr<audio_alsa_source> audio_alsa_source_sptr;
 
 /*!
  * \brief audio source using ALSA
+ * \ingroup audio_blk
  *
  * The source has between 1 and N input streams of floats, where N is
  * depends on the hardware characteristics of the selected device.
diff --git a/gr-audio/lib/jack/audio_jack_sink.h b/gr-audio/lib/jack/audio_jack_sink.h
index a11863ee0..5500b3641 100644
--- a/gr-audio/lib/jack/audio_jack_sink.h
+++ b/gr-audio/lib/jack/audio_jack_sink.h
@@ -32,6 +32,7 @@ int jack_sink_process (jack_nframes_t nframes, void *arg);
 
 /*!
  * \brief audio sink using JACK
+ * \ingroup audio_blk
  *
  * The sink has one input stream of floats.
  *
diff --git a/gr-audio/lib/jack/audio_jack_source.h b/gr-audio/lib/jack/audio_jack_source.h
index 858f34528..a155bf95b 100644
--- a/gr-audio/lib/jack/audio_jack_source.h
+++ b/gr-audio/lib/jack/audio_jack_source.h
@@ -32,6 +32,7 @@ int jack_source_process (jack_nframes_t nframes, void *arg);
 
 /*!
  * \brief audio source using JACK
+ * \ingroup audio_blk
  *
  * The source has one input stream of floats.
  *
diff --git a/gr-audio/lib/oss/audio_oss_sink.h b/gr-audio/lib/oss/audio_oss_sink.h
index 0d7280c2f..47b1407d3 100644
--- a/gr-audio/lib/oss/audio_oss_sink.h
+++ b/gr-audio/lib/oss/audio_oss_sink.h
@@ -28,6 +28,7 @@
 
 /*!
  * \brief audio sink using OSS
+ * \ingroup audio_blk
  *
  * input signature is one or two streams of floats.
  * Input samples must be in the range [-1,1].
diff --git a/gr-audio/lib/oss/audio_oss_source.h b/gr-audio/lib/oss/audio_oss_source.h
index b20ef5c05..df9f68e42 100644
--- a/gr-audio/lib/oss/audio_oss_source.h
+++ b/gr-audio/lib/oss/audio_oss_source.h
@@ -28,6 +28,7 @@
 
 /*!
  * \brief audio source using OSS
+ * \ingroup audio_blk
  *
  * Output signature is one or two streams of floats.
  * Output samples will be in the range [-1,1].
diff --git a/gr-audio/lib/osx/audio_osx_sink.h b/gr-audio/lib/osx/audio_osx_sink.h
index 13bd95d53..e7598097d 100644
--- a/gr-audio/lib/osx/audio_osx_sink.h
+++ b/gr-audio/lib/osx/audio_osx_sink.h
@@ -31,6 +31,7 @@
 
 /*!
  * \brief audio sink using OSX
+ * \ingroup audio_blk
  *
  * input signature is one or two streams of floats.
  * Input samples must be in the range [-1,1].
diff --git a/gr-audio/lib/osx/audio_osx_source.h b/gr-audio/lib/osx/audio_osx_source.h
index a373ea94f..435172a2c 100644
--- a/gr-audio/lib/osx/audio_osx_source.h
+++ b/gr-audio/lib/osx/audio_osx_source.h
@@ -31,6 +31,7 @@
 
 /*!
  * \brief audio source using OSX
+ * \ingroup audio_blk
  *
  * Input signature is one or two streams of floats.
  * Samples must be in the range [-1,1].
diff --git a/gr-audio/lib/portaudio/audio_portaudio_sink.h b/gr-audio/lib/portaudio/audio_portaudio_sink.h
index 6426a32ac..04a881f7e 100644
--- a/gr-audio/lib/portaudio/audio_portaudio_sink.h
+++ b/gr-audio/lib/portaudio/audio_portaudio_sink.h
@@ -34,7 +34,8 @@ PaStreamCallback portaudio_sink_callback;
 
 
 /*!
- * \ Audio sink using PORTAUDIO
+ * \brief Audio sink using PORTAUDIO
+ * \ingroup audio_blk
  *
  * Input samples must be in the range [-1,1].
  */
diff --git a/gr-audio/lib/portaudio/audio_portaudio_source.h b/gr-audio/lib/portaudio/audio_portaudio_source.h
index 245b3410b..b555bc759 100644
--- a/gr-audio/lib/portaudio/audio_portaudio_source.h
+++ b/gr-audio/lib/portaudio/audio_portaudio_source.h
@@ -33,7 +33,8 @@ PaStreamCallback portaudio_source_callback;
 
 
 /*!
- * \ Audio source using PORTAUDIO
+ * \brief Audio source using PORTAUDIO
+ * \ingroup audio_blk
  *
  * Input samples must be in the range [-1,1].
  */
diff --git a/gr-audio/lib/windows/audio_windows_sink.h b/gr-audio/lib/windows/audio_windows_sink.h
index 6819bd448..d4ca259b3 100644
--- a/gr-audio/lib/windows/audio_windows_sink.h
+++ b/gr-audio/lib/windows/audio_windows_sink.h
@@ -34,6 +34,7 @@
 
 /*!
  * \brief audio sink using winmm mmsystem (win32 only)
+ * \ingroup audio_blk
  *
  * input signature is one or two streams of floats.
  * Input samples must be in the range [-1,1].
diff --git a/gr-audio/lib/windows/audio_windows_source.h b/gr-audio/lib/windows/audio_windows_source.h
index 36311968d..9cb789576 100644
--- a/gr-audio/lib/windows/audio_windows_source.h
+++ b/gr-audio/lib/windows/audio_windows_source.h
@@ -28,6 +28,7 @@
 
 /*!
  * \brief audio source using winmm mmsystem (win32 only)
+ * \ingroup audio_blk
  *
  * Output signature is one or two streams of floats.
  * Output samples will be in the range [-1,1].