From 67440ce084cc79be821841cc07aeacd0f0df3bfe Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Olivier=20Cr=C3=AAte?= <olivier.crete@collabora.com>
Date: Thu, 26 Jun 2014 17:22:25 -0400
Subject: [PATCH] devicemonitor: Improve documentation

---
 gst/gstdevicemonitor.c         | 51 ++++++++++++++++++++++++++++++++++
 gst/gstdeviceprovider.c        |  4 +--
 gst/gstdeviceproviderfactory.c |  5 ++--
 gst/gstmessage.c               |  8 +++---
 4 files changed, 60 insertions(+), 8 deletions(-)

diff --git a/gst/gstdevicemonitor.c b/gst/gstdevicemonitor.c
index 383f130d38..eb8759c843 100644
--- a/gst/gstdevicemonitor.c
+++ b/gst/gstdevicemonitor.c
@@ -34,6 +34,57 @@
  * The device monitor will monitor all devices matching the filters that
  * the application has set.
  *
+ *
+ * The basic use pattern of an iterator is as follows:
+ * |[
+ *   static gboolean
+ *   my_bus_func (GstBus * bus, GstMessage * message, gpointer user_data)
+ *   {
+ *      GstDevice *device;
+ *      gchar name;
+ *
+ *      switch (GST_MESSAGE_TYPE (message)) {
+ *        case GST_MESSAGE_DEVICE_ADDED:
+ *          gst_message_parse_device_added (message, &device);
+ *          name = gst_device_get_display_name (device);
+ *          g_print("Device added: %s\n", name);
+ *          g_free (name);
+ *          break;
+ *        case GST_MESSAGE_DEVICE_REMOVED:
+ *          gst_message_parse_device_removed (message, &device);
+ *          name = gst_device_get_display_name (device);
+ *          g_print("Device removed: %s\n", name);
+ *          g_free (name);
+ *          break;
+ *        default:
+ *          break;
+ *      }
+ *
+ *      return G_SOURCE_CONTINUE;
+ *   }
+ *
+ *   GstDeviceMonitor *
+ *   setup_raw_video_source_device_monitor (void) {
+ *      GstDeviceMonitor *monitor;
+ *      GstBus *bus;
+ *      GstCaps *caps;
+ *
+ *      monitor = gst_device_monitor_new ();
+ *
+ *      bus = gst_device_monitor_get_bus (monitor);
+ *      gst_bus_add_watch (bus, my_bus_func, NULL);
+ *      gst_object_unref (bus);
+ *
+ *      caps = gst_caps_new_simple_empty ("video/x-raw");
+ *      gst_device_monitor_add_filter (monitor, "Video/Source", caps);
+ *      gst_caps_unref (caps);
+ *
+ *      gst_device_monitor_start (monitor);
+ *
+ *      return monitor;
+ *   }
+ * ]|
+ *
  * Since: 1.4
  */
 
diff --git a/gst/gstdeviceprovider.c b/gst/gstdeviceprovider.c
index e06f41d3e5..ea912004bb 100644
--- a/gst/gstdeviceprovider.c
+++ b/gst/gstdeviceprovider.c
@@ -22,7 +22,7 @@
 /**
  * SECTION:gstdeviceprovider
  * @short_description: A device provider
- * @see_also: #GstDevice, #GstGlobalDeviceMonitor
+ * @see_also: #GstDevice, #GstDeviceMonitor
  *
  * A #GstDeviceProvider subclass is provided by a plugin that handles devices
  * if there is a way to programatically list connected devices. It can also
@@ -31,7 +31,7 @@
  * Each #GstDeviceProvider subclass is a singleton, a plugin should
  * normally provide a single subclass for all devices.
  *
- * Applications would normally use a #GstGlobalDeviceMonitor to monitor devices
+ * Applications would normally use a #GstDeviceMonitor to monitor devices
  * from all relevant providers.
  *
  * Since: 1.4
diff --git a/gst/gstdeviceproviderfactory.c b/gst/gstdeviceproviderfactory.c
index 2e9d7a9d4a..73035af670 100644
--- a/gst/gstdeviceproviderfactory.c
+++ b/gst/gstdeviceproviderfactory.c
@@ -30,8 +30,9 @@
  * GstDeviceProviderfactory can be added to a #GstPlugin as it is also a
  * #GstPluginFeature.
  *
- * Use the gst_device_provider_factory_find() and gst_device_provider_factory_create()
- * functions to create device provider instances or use gst_device_provider_factory_make() as a
+ * Use the gst_device_provider_factory_find() and
+ * gst_device_provider_factory_create() functions to create device
+ * provider instances or use gst_device_provider_factory_make() as a
  * convenient shortcut.
  *
  * Since: 1.4
diff --git a/gst/gstmessage.c b/gst/gstmessage.c
index 9119a003d7..f4b3dedb8c 100644
--- a/gst/gstmessage.c
+++ b/gst/gstmessage.c
@@ -2340,7 +2340,7 @@ gst_message_parse_have_context (GstMessage * message, GstContext ** context)
  * @device: (transfer none): The new #GstDevice
  *
  * Creates a new device-added message. The device-added message is produced by
- * #GstDeviceProvider or a #GstGlobalDeviceMonitor. They announce the appearance
+ * #GstDeviceProvider or a #GstlDeviceMonitor. They announce the appearance
  * of monitored devices.
  *
  * Returns: a newly allocated #GstMessage
@@ -2370,7 +2370,7 @@ gst_message_new_device_added (GstObject * src, GstDevice * device)
  *  pointer to the new #GstDevice, or %NULL
  * 
  * Parses a device-added message. The device-added message is produced by
- * #GstDeviceProvider or a #GstGlobalDeviceMonitor. It announces the appearance
+ * #GstDeviceProvider or a #GstDeviceMonitor. It announces the appearance
  * of monitored devices.
  *
  * Since: 1.4
@@ -2392,7 +2392,7 @@ gst_message_parse_device_added (GstMessage * message, GstDevice ** device)
  * @device: (transfer none): The removed #GstDevice
  *
  * Creates a new device-removed message. The device-removed message is produced
- * by #GstDeviceProvider or a #GstGlobalDeviceMonitor. They announce the
+ * by #GstDeviceProvider or a #GstDeviceMonitor. They announce the
  * disappearance of monitored devices.
  *
  * Returns: a newly allocated #GstMessage
@@ -2422,7 +2422,7 @@ gst_message_new_device_removed (GstObject * src, GstDevice * device)
  *  pointer to the removed #GstDevice, or %NULL
  *
  * Parses a device-removed message. The device-removed message is produced by
- * #GstDeviceProvider or a #GstGlobalDeviceMonitor. It announces the
+ * #GstDeviceProvider or a #GstDeviceMonitor. It announces the
  * disappearance of monitored devices.
  *
  * Since: 1.4