[glibmm] ArrayHandle, ListHandle, SListHandle: Document these as almost-deprecated.

[Murray Cumming <murrayc src gnome org>]

commit f45e7f710a21db3c98e5f7066ee60300e0355ac8
Author: Murray Cumming <murrayc murrayc com>
Date:   Fri Jan 28 23:29:58 2011 +0100

    ArrayHandle, ListHandle, SListHandle: Document these as almost-deprecated.
    
    * glib/glibmm/arrayhandle.h:
    * glib/glibmm/listhandle.h:
    * glib/glibmm/slisthandle.h: Mention that we try not to use these now,
    though we cannot actually deprecate them yet without forcing other libraries
    such as pangomm to deprecate the methods that use them, which they cannot
    really do because they cannot just add a method overload without introducing
    ambiguity.

 ChangeLog                 |   12 ++++++++++++
 glib/glibmm/arrayhandle.h |   15 +++++++++++++--
 glib/glibmm/listhandle.h  |   12 ++++++++----
 glib/glibmm/slisthandle.h |   10 +++++++---
 4 files changed, 40 insertions(+), 9 deletions(-)
---
diff --git a/ChangeLog b/ChangeLog
index 8e20a3f..defc932 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,15 @@
+2011-01-28  Murray Cumming  <murrayc murrayc com>
+
+	ArrayHandle, ListHandle, SListHandle: Document these as almost-deprecated.
+
+	* glib/glibmm/arrayhandle.h:
+	* glib/glibmm/listhandle.h:
+	* glib/glibmm/slisthandle.h: Mention that we try not to use these now, 
+	though we cannot actually deprecate them yet without forcing other libraries 
+	such as pangomm to deprecate the methods that use them, which they cannot 
+	really do because they cannot just add a method overload without introducing 
+	ambiguity.
+
 2011-01-27  Chris Kühl  <chrisk openismus com>
 
 	Changed glib include to build cleanly with GLIB_DISABLE_SINGLE_INCLUDES.
diff --git a/glib/glibmm/arrayhandle.h b/glib/glibmm/arrayhandle.h
index 9048d5c..c66c871 100644
--- a/glib/glibmm/arrayhandle.h
+++ b/glib/glibmm/arrayhandle.h
@@ -178,8 +178,13 @@ private:
 } // namespace Container_Helpers
 
 
-/** If a method takes this as an argument, or has this as a return type, then you can use a standard
- * container such as std::list or std::vector.
+/** This is an intermediate type. When a method takes this, or returns this, you
+ * should use a standard C++ container of your choice, such as std::list or 
+ * std::vector.
+ *
+ * However, this is not used in new API. We now prefer to just use std::vector, 
+ * which is less flexibile, but makes the API clearer.
+ *
  * @ingroup ContHandles
  */
 template < class T, class Tr = Glib::Container_Helpers::TypeTraits<T> >
@@ -234,8 +239,14 @@ private:
   ArrayHandle<T, Tr>& operator=(const ArrayHandle<T,Tr>&);
 };
 
+//TODO: Remove this when we can break glibmm API.
 /** If a method takes this as an argument, or has this as a return type, then you can use a standard
  * container such as std::list<Glib::ustring> or std::vector<Glib::ustring>.
+ *
+ *
+ * However, this is not used in new API. We now prefer to just use std::vector, 
+ * which is less flexibile, but makes the API clearer.
+ *
  * @ingroup ContHandles
  */
 typedef ArrayHandle<Glib::ustring> StringArrayHandle;
diff --git a/glib/glibmm/listhandle.h b/glib/glibmm/listhandle.h
index 13359b6..4716064 100644
--- a/glib/glibmm/listhandle.h
+++ b/glib/glibmm/listhandle.h
@@ -119,8 +119,6 @@ struct ListSourceTraits<Tr,const Cont[N]> : ListSourceTraits<Tr,Cont[N]>
 
 /**
  * @ingroup ContHelpers
- * If a method takes this as an argument, or has this as a return type, then you can use a standard
- * container such as std::list or std::vector.
  */
 template <class Tr>
 class ListHandleIterator
@@ -150,8 +148,14 @@ private:
 
 } // namespace Container_Helpers
 
-
-/**
+//TODO: Remove this when we can break glibmm API.
+/** This is an intermediate type. When a method takes this, or returns this, you
+ * should use a standard C++ container of your choice, such as std::list or 
+ * std::vector.
+ *
+ * However, this is not used in new API. We now prefer to just use std::vector, 
+ * which is less flexibile, but makes the API clearer.
+ *
  * @ingroup ContHandles
  */
 template < class T, class Tr = Glib::Container_Helpers::TypeTraits<T> >
diff --git a/glib/glibmm/slisthandle.h b/glib/glibmm/slisthandle.h
index 70028c3..2885e94 100644
--- a/glib/glibmm/slisthandle.h
+++ b/glib/glibmm/slisthandle.h
@@ -119,8 +119,6 @@ struct SListSourceTraits<Tr,const Cont[N]> : SListSourceTraits<Tr,Cont[N]>
 
 /**
  * @ingroup ContHelpers
- * If a method takes this as an argument, or has this as a return type, then you can use a standard
- * container such as std::list or std::vector.
  */
 template <class Tr>
 class SListHandleIterator
@@ -151,7 +149,13 @@ private:
 } // namespace Container_Helpers
 
 
-/**
+//TODO: Remove this when we can break glibmm API.
+/** This is an intermediate type. When a method takes this, or returns this, you
+ * should use a standard C++ container of your choice, such as std::list or 
+ * std::vector.
+ *
+ * However, this is not used in new API. We now prefer to just use std::vector, 
+ * which is less flexibile, but makes the API clearer.
  * @ingroup ContHandles
  */
 template < class T, class Tr = Glib::Container_Helpers::TypeTraits<T> >