[glibmm] Vector utils: Corrected documentation and extended it bit.

[Murray Cumming <murrayc src gnome org>]

commit ad59743628383374a590508d474ae81fbb74b6cd
Author: Krzesimir Nowak <qdlacz gmail com>
Date:   Mon Jan 31 20:32:21 2011 +0100

    Vector utils: Corrected documentation and extended it bit.
    
    * glib/glibmm/vectorutils.h: Documented important parts of *Keeper classes
    and corrected examples in *Handler classes. The documentation mostly tries
    to explain memory management.

 ChangeLog                 |    8 ++
 glib/glibmm/vectorutils.h |  173 +++++++++++++++++++++++++++++++++++++++++++--
 2 files changed, 175 insertions(+), 6 deletions(-)
---
diff --git a/ChangeLog b/ChangeLog
index 6f41990..ad3edeb 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,11 @@
+2011-01-21  Krzesimir Nowak  <qdlacz gmail com>
+
+	Vector utils: Corrected documentation and extended it bit.
+
+	* glib/glibmm/vectorutils.h: Documented important parts of *Keeper classes
+	and corrected examples in *Handler classes. The documentation mostly tries
+	to explain memory management.
+
 2011-01-30  Murray Cumming  <murrayc murrayc com>
 
 	Vector utils: Added simple documentation.
diff --git a/glib/glibmm/vectorutils.h b/glib/glibmm/vectorutils.h
index b724d8f..87a9151 100644
--- a/glib/glibmm/vectorutils.h
+++ b/glib/glibmm/vectorutils.h
@@ -242,6 +242,28 @@ private:
   const GSList* node_;
 };
 
+/** A keeper class for C array.
+ *
+ * Primarily used by C++ wrappers like gtkmm.
+ *
+ * Its main purpose is to free its data when they are not needed. What will be
+ * destroyed depends on passed ownership upon construction.
+ *
+ * The most common usage of Glib::ArrayKeeper is getting its data when converting
+ * std::vector to a C array:
+ * @code
+ * void G::Temp::do_something(const std::vector<int>& v)
+ * {
+ *   g_temp_do_something(gobj(), Glib::ArrayHandler<int>::vector_to_array(v).data());
+ * }
+ * @endcode
+ * Variables of this class are seldom defined directly - it is mostly used as
+ * a temporary variable returned by Glib::ArrayHandler::vector_to_array().
+ *
+ * Note that the usage above is correct with regards to C++ standard point 12.2.3.
+ * That means that data returned by data() method is valid through whole
+ * g_temp_do_something function and is destroyed, when this function returns.
+ */
 template <typename Tr>
 class ArrayKeeper
 {
@@ -249,10 +271,28 @@ public:
   typedef typename Tr::CppType        CppType;
   typedef typename Tr::CType          CType;
 
+  /** Constructs an ArrayKeeper holding @a array of size @array_size.
+   * @a ownership tells what should be destroyed with keeper destruction:
+   * <ul>
+   * <li>Glib::OWNERSHIP_NONE - keeper won't destroy data it holds.</li>
+   * <li>Glib::OWNERSHIP_SHALLOW - keeper will destroy only container it holds.</li>
+   * <li>Glib::OWNERSHIP_DEEP - keeper will destroy data and container it holds.</li>
+   * </ul>
+   *
+   * @param array - C array to hold.
+   * @param array_size - length of @a array.
+   * @param ownership - ownership definition.
+   */
   explicit inline ArrayKeeper(const CType* array, size_t array_size, Glib::OwnershipType ownership);
   inline ArrayKeeper(const ArrayKeeper& keeper);
   ~ArrayKeeper();
 
+  /** Gets data the keeper holds.
+   *
+   * Note that this data is owned by the keeper, so there is no need to free it.
+   *
+   * @return C array owned by ArrayKeeper.
+   */
   inline CType* data() const;
 
 private:
@@ -261,6 +301,28 @@ private:
   mutable Glib::OwnershipType ownership_;
 };
 
+/** A keeper class for GList.
+ *
+ * Primarily used by C++ wrappers like gtkmm.
+ *
+ * Its main purpose is to free its data when they are not needed. What will be
+ * destroyed depends on passed ownership upon construction.
+ *
+ * The most common usage of Glib::GListKeeper is getting its data when converting
+ * std::vector to a GList*:
+ * @code
+ * void G::Temp::do_something(const std::vector<int>& v)
+ * {
+ *   g_temp_do_something(gobj(), Glib::ListHandler<int>::vector_to_list(v).data());
+ * }
+ * @endcode
+ * Variables of this class are seldom defined directly - it is mostly used as
+ * a temporary variable returned by Glib::ListHandler::vector_to_list().
+ *
+ * Note that the usage above is correct with regards to C++ standard point 12.2.3.
+ * That means that data returned by data() method is valid through whole
+ * g_temp_do_something function and is destroyed, when this function returns.
+ */
 template <typename Tr>
 class GListKeeper
 {
@@ -268,10 +330,27 @@ public:
   typedef typename Tr::CppType        CppType;
   typedef typename Tr::CType          CType;
 
+  /** Constructs an GListKeeper holding @a glist.
+   * @a ownership tells what should be destroyed with keeper destruction:
+   * <ul>
+   * <li>Glib::OWNERSHIP_NONE - keeper won't destroy data it holds.</li>
+   * <li>Glib::OWNERSHIP_SHALLOW - keeper will destroy only container it holds.</li>
+   * <li>Glib::OWNERSHIP_DEEP - keeper will destroy data and container it holds.</li>
+   * </ul>
+   *
+   * @param glist - GList* to hold.
+   * @param ownership - ownership definition.
+   */
   explicit inline GListKeeper(const GList* glist, Glib::OwnershipType ownership);
   inline GListKeeper(const GListKeeper& keeper);
   ~GListKeeper();
 
+  /** Gets data the keeper holds.
+   *
+   * Note that this data is owned by the keeper, so there is no need to free it.
+   *
+   * @return GList* owned by GListKeeper.
+   */
   inline GList* data() const;
 
 private:
@@ -279,6 +358,28 @@ private:
   mutable Glib::OwnershipType ownership_;
 };
 
+/** A keeper class for GSList.
+ *
+ * Primarily used by C++ wrappers like gtkmm.
+ *
+ * Its main purpose is to free its data when they are not needed. What will be
+ * destroyed depends on passed ownership upon construction.
+ *
+ * The most common usage of Glib::GSListKeeper is getting its data when converting
+ * std::vector to a GSList*:
+ * @code
+ * void G::Temp::do_something(const std::vector<int>& v)
+ * {
+ *   g_temp_do_something(gobj(), Glib::SListHandler<int>::vector_to_slist(v).data());
+ * }
+ * @endcode
+ * Variables of this class are seldom defined directly - it is mostly used as
+ * a temporary variable returned by Glib::SListHandler::vector_to_slist().
+ *
+ * Note that the usage above is correct with regards to C++ standard point 12.2.3.
+ * That means that data returned by data() method is valid through whole
+ * g_temp_do_something function and is destroyed, when this function returns.
+ */
 template <typename Tr>
 class GSListKeeper
 {
@@ -286,10 +387,27 @@ public:
   typedef typename Tr::CppType        CppType;
   typedef typename Tr::CType          CType;
 
+  /** Constructs an GSListKeeper holding @a gslist.
+   * @a ownership tells what should be destroyed with keeper destruction:
+   * <ul>
+   * <li>Glib::OWNERSHIP_NONE - keeper won't destroy data it holds.</li>
+   * <li>Glib::OWNERSHIP_SHALLOW - keeper will destroy only container it holds.</li>
+   * <li>Glib::OWNERSHIP_DEEP - keeper will destroy data and container it holds.</li>
+   * </ul>
+   *
+   * @param gslist - GList* to hold.
+   * @param ownership - ownership definition.
+   */
   explicit inline GSListKeeper(const GSList* gslist, Glib::OwnershipType ownership);
   inline GSListKeeper(const GSListKeeper& keeper);
   ~GSListKeeper();
 
+  /** Gets data the keeper holds.
+   *
+   * Note that this data is owned by the keeper, so there is no need to free it.
+   *
+   * @return GSList* owned by GSListKeeper.
+   */
   inline GSList* data() const;
 
 private:
@@ -302,15 +420,34 @@ private:
 // Note that this is a struct instead of templated functions because standard template arguments
 // for function templates is a C++0x feature.
 /** A utility for converting between std::vector and plain C arrays.
- * This would normally only be used by glibmm or gtkmm itself, or similar 
+ * This would normally only be used by glibmm or gtkmm itself, or similar
  * libraries that wrap C APIs.
  *
  * For instance:
  * @code
- * std::vector<TimeCoord> vec = Glib::ArrayHandler<TimeCoord, TimeCoordPtrTraits>::array_to_vector(array, array_size, Glib::OWNERSHIP_DEEP);
+ * std::vector<Glib::ustring> PixbufFormat::get_mime_types() const
+ * {
+ *   return Glib::ArrayHandler<Glib::ustring>::array_to_vector(gdk_pixbuf_format_get_mime_types(const_cast<GdkPixbufFormat*>(gobj())), Glib::OWNERSHIP_DEEP);
+ * }
  * @endcode
  * or
  * @code
+ * void Display::store_clipboard(const Glib::RefPtr<Gdk::Window>& clipboard_window, guint32 time_, const std::vector<Glib::ustring>& targets)
+ * {
+ *   if (!targets.size ())
+ *   {
+ *     gdk_display_store_clipboard(gobj(),
+ *                                 Glib::unwrap (clipboard_window),
+ *                                 time_,
+ *                                 Glib::ArrayHandler<Glib::ustring, AtomUstringTraits>::vector_to_array(targets).data (),
+ *                                 targets.size ());
+ *   }
+ * }
+ * @endcode
+ * Note that usage below is wrong - data() returns a pointer to data owned by
+ * a temporary ArrayKeeper returned by vector_to_array(), which is destroyed at
+ * the end of this instruction. For details, see Glib::ArrayKeeper.
+ * @code
  * const char** array = Glib::ArrayHandler<Glib::ustring>::vector_to_array(vec).data ();
  * @endcode
  */
@@ -347,15 +484,27 @@ public:
 };
 
 /** A utility for converting between std::vector and GList.
- * This would normally only be used by glibmm or gtkmm itself, or similar 
+ * This would normally only be used by glibmm or gtkmm itself, or similar
  * libraries that wrap C APIs.
  *
  * For instance:
  * @code
- * Glib::ListHandler< Glib::RefPtr<Window> >::list_to_vector(gdk_window_get_children(gobj()), Glib::OWNERSHIP_SHALLOW);
+ * std::vector< Glib::RefPtr<Window> > Window::get_children()
+ * {
+ *   return Glib::ListHandler<Glib::RefPtr<Window> >::list_to_vector(gdk_window_get_children(gobj()), Glib::OWNERSHIP_SHALLOW);
+ * }
  * @endcode
  * or
  * @code
+ * void Window::set_icon_list(const std::vector< Glib::RefPtr<Gdk::Pixbuf> >& pixbufs)
+ * {
+ *   gdk_window_set_icon_list(gobj(), Glib::ListHandler<Glib::RefPtr<Gdk::Pixbuf> >::vector_to_list(pixbufs).data ());
+ * }
+ * @endcode
+ * Note that usage below is wrong - data() returns a pointer to data owned by
+ * a temporary ListKeeper returned by vector_to_list(), which is destroyed at
+ * the end of this instruction. For details, see Glib::ListKeeper.
+ * @code
  * GList* glist = Glib::ListHandler<Glib::RefPtr<Gdk::Pixbuf> >::vector_to_list(pixbufs).data();
  * @endcode
  */
@@ -375,15 +524,27 @@ public:
 };
 
 /** A utility for converting between std::vector and GSList.
- * This would normally only be used by glibmm or gtkmm itself, or similar 
+ * This would normally only be used by glibmm or gtkmm itself, or similar
  * libraries that wrap C APIs.
  *
  * For instance:
  * @code
- * std::vector< Glib::RefPtr<Display> > vec =  Glib::SListHandler<Glib::RefPtr<Display> >::slist_to_vector(gdk_display_manager_list_displays(gobj()), Glib::OWNERSHIP_SHALLOW);
+ * std::vector< Glib::RefPtr<Display> > DisplayManager::list_displays()
+ * {
+ *   return Glib::SListHandler<Glib::RefPtr<Display> >::slist_to_vector(gdk_display_manager_list_displays(gobj()), Glib::OWNERSHIP_SHALLOW);
+ * }
  * @endcode
  * or
  * @code
+ * void Stuff::set_slist(const std::vector<int>& ints)
+ * {
+ *   g_stuff_set_slist(gobj(), Glib::SListHandler<int>::vector_to_slist(ints).data ());
+ * }
+ * @endcode
+ * Note that usage below is wrong - data() returns a pointer to data owned by
+ * a temporary SListKeeper returned by vector_to_slist(), which is destroyed at
+ * the end of this instruction. For details, see Glib::SListKeeper.
+ * @code
  * GSList* gslist = Glib::SListHandler< Glib::RefPtr<Display> >::vector_to_slist(vec).data();
  * @endcode
  */