[gtkmm] Gtk::TreeNodeChildren: Deprecate the reverse iterator

[Kjell Ahlstedt <kjellahl src gnome org>]

commit 2956be4830c421f1dabc93e1fb5e0ae19bf38d46
Author: Kjell Ahlstedt <kjell ahlstedt bredband net>
Date:   Mon Sep 12 10:16:10 2016 +0200

    Gtk::TreeNodeChildren: Deprecate the reverse iterator
    
    * gtk/src/treeiter.hg:
    * gtk/src/treemodel.hg: Deprecate Gtk::TreeNodeChildren::reverse_iterator.
    It has never worked and it's difficult to fix. Even if fixed, it would
    probably be used very seldom. Bug #554889

 gtk/src/treeiter.hg  |   28 ++++++++++++++++++++++++++--
 gtk/src/treemodel.hg |   13 ++++++++++++-
 2 files changed, 38 insertions(+), 3 deletions(-)
---
diff --git a/gtk/src/treeiter.hg b/gtk/src/treeiter.hg
index a6a5b0e..c1ebf26 100644
--- a/gtk/src/treeiter.hg
+++ b/gtk/src/treeiter.hg
@@ -371,34 +371,58 @@ public:
   typedef unsigned int  size_type;
   typedef int           difference_type;
   typedef Gtk::TreeIter iterator;
+  typedef Gtk::TreeIter const_iterator; //TODO: Make it a real const_iterator.
 
+  // Reverse iterator: https://bugzilla.gnome.org/show_bug.cgi?id=554889
+_DEPRECATE_IFDEF_START
   #ifndef GLIBMM_HAVE_SUN_REVERSE_ITERATOR
+    /** @deprecated This reverse_iterator has never worked,
+     * use the normal (forward) iterator instead.
+     */
     typedef std::reverse_iterator<iterator> reverse_iterator;
   #else
+    /** @deprecated This reverse_iterator has never worked,
+     * use the normal (forward) iterator instead.
+     */
     typedef std::reverse_iterator<iterator, std::random_access_iterator_tag,
                                   int, int&, int*, std::ptrdiff_t> reverse_iterator;
   #endif
 
-    typedef Gtk::TreeIter const_iterator; //TODO: Make it a real const_iterator.
-
   #ifndef GLIBMM_HAVE_SUN_REVERSE_ITERATOR
+    /** @deprecated This reverse_iterator has never worked,
+     * use the normal (forward) iterator instead.
+     */
     typedef std::reverse_iterator<const_iterator> const_reverse_iterator;
   #else
+    /** @deprecated This reverse_iterator has never worked,
+     * use the normal (forward) iterator instead.
+     */
     typedef std::reverse_iterator<const_iterator, std::random_access_iterator_tag,
                                   int, const int&, const int*, std::ptrdiff_t> const_reverse_iterator;
   #endif
+_DEPRECATE_IFDEF_END
 
   iterator begin();
   const_iterator begin() const;
   iterator end();
   const_iterator end()   const;
 
+_DEPRECATE_IFDEF_START
   // Note: there is no advantage in not inlining these methods.
   // We can't change them without breaking ABI anyway.
+  /** @deprecated Use begin() or end() instead.
+   */
   reverse_iterator       rbegin()       { return reverse_iterator(end());         }
+  /** @deprecated Use begin() or end() instead.
+   */
   reverse_iterator       rend()         { return reverse_iterator(begin());       }
+  /** @deprecated Use begin() or end() instead.
+   */
   const_reverse_iterator rbegin() const { return const_reverse_iterator(end());   }
+  /** @deprecated Use begin() or end() instead.
+   */
   const_reverse_iterator rend()   const { return const_reverse_iterator(begin()); }
+_DEPRECATE_IFDEF_END
 
   value_type operator[](size_type index) const;
 
diff --git a/gtk/src/treemodel.hg b/gtk/src/treemodel.hg
index 55faf7f..799f39a 100644
--- a/gtk/src/treemodel.hg
+++ b/gtk/src/treemodel.hg
@@ -98,9 +98,20 @@ public:
 
   typedef TreeNodeChildren Children;
   typedef Children::iterator iterator;
-  typedef Children::reverse_iterator reverse_iterator;
   typedef Children::const_iterator const_iterator;
+
+  // Reverse iterator: https://bugzilla.gnome.org/show_bug.cgi?id=554889
+_DEPRECATE_IFDEF_START
+  /** @deprecated This reverse_iterator has never worked,
+   * use the normal (forward) iterator instead.
+   */
+  typedef Children::reverse_iterator reverse_iterator;
+
+  /** @deprecated This reverse_iterator has never worked,
+   * use the normal (forward) iterator instead.
+   */
   typedef Children::const_reverse_iterator const_reverse_iterator;
+_DEPRECATE_IFDEF_END
 
   typedef TreeRow Row;
   typedef TreePath Path;