[gnome-bluetooth/gnome-3-2] lib: Add doc about GtkTreeModelFilter shortcomings

[Bastien Nocera <hadess src gnome org>]

commit 2c99c578feffb464237a4b2e55c465bde9df6a53
Author: Bastien Nocera <hadess hadess net>
Date:   Wed Jan 18 13:59:28 2012 +0000

    lib: Add doc about GtkTreeModelFilter shortcomings
    
    Such as the possible lack of row-inserted/row-deleted/row-changed
    signals, and the necessity to monitor the child-model of that filter.
    
    Conflicts:
    
    	lib/bluetooth-client.c

 lib/bluetooth-client.c |    9 ++++++---
 1 files changed, 6 insertions(+), 3 deletions(-)
---
diff --git a/lib/bluetooth-client.c b/lib/bluetooth-client.c
index e2f66c7..fe79d33 100644
--- a/lib/bluetooth-client.c
+++ b/lib/bluetooth-client.c
@@ -1187,7 +1187,7 @@ GtkTreeModel *bluetooth_client_get_model (BluetoothClient *client)
  * @data: user data to pass to gtk_tree_model_filter_set_visible_func()
  * @destroy: a destroy function for gtk_tree_model_filter_set_visible_func()
  *
- * Returns a #GtkTreeModel of devices filtered using the @func, @data and @destroy arguments to pass to gtk_tree_model_filter_set_visible_func().
+ * Returns a #GtkTreeModelFilter of devices filtered using the @func, @data and @destroy arguments to pass to gtk_tree_model_filter_set_visible_func().
  *
  * Return value: (transfer full): a #GtkTreeModel object.
  **/
@@ -1234,7 +1234,7 @@ static gboolean adapter_filter(GtkTreeModel *model,
  * bluetooth_client_get_adapter_model:
  * @client: a #BluetoothClient object
  *
- * Returns a filtered #GtkTreeModel with only adapters present.
+ * Returns a #GtkTreeModelFilter with only adapters present.
  *
  * Return value: (transfer full): a #GtkTreeModel object.
  **/
@@ -1251,7 +1251,10 @@ GtkTreeModel *bluetooth_client_get_adapter_model (BluetoothClient *client)
  * @client: a #BluetoothClient object
  * @adapter: a #DBusGProxy of the adapter object, or %NULL to get the default adapter.
  *
- * Returns a filtered #GtkTreeModel with only devices belonging to the selected adapter listed. Note that the model will follow a specific adapter, and will not follow the default-adapter when %NULL is passed.
+ * Returns a #GtkTreeModelFilter with only devices belonging to the @adapter listed.
+ * Note that the model will follow a specific adapter, and will not follow the default adapter.
+ * Also note that due to the way #GtkTreeModelFilter works, you will probably want to
+ * monitor signals on the "child-model" #GtkTreeModel to monitor for changes.
  *
  * Return value: (transfer full): a #GtkTreeModel object.
  **/