[gtkmm] TreeModel: Improve docs of foreach*() functions

[Daniel Boles <dboles src gnome org>]

commit 244420dfbdba711dca72bc18953a7806532b16b5
Author: Daniel Boles <dboles src gmail com>
Date:   Mon May 8 09:58:32 2017 +0100

    TreeModel: Improve docs of foreach*() functions
    
    • Fix example slots to have the correct bool return type; they were void
    • Don’t use example as 1st paragraph as it ends with ;. which looks odd
    • Open by explaining what the typedef is for, with link to its foreach()
    • For each foreach*(), name and link to its type of slot in the comment

 gtk/src/treemodel.hg |   30 +++++++++++++++++++++---------
 1 files changed, 21 insertions(+), 9 deletions(-)
---
diff --git a/gtk/src/treemodel.hg b/gtk/src/treemodel.hg
index 929bebf..12e8e80 100644
--- a/gtk/src/treemodel.hg
+++ b/gtk/src/treemodel.hg
@@ -146,42 +146,54 @@ public:
 
   _IGNORE(gtk_tree_model_foreach)
 
-  /** For example,
-   * void on_foreach(const Gtk::TreeModel::iterator& iter);
+  /** The type of callback slot used by foreach_iter().
    *
    * If the callback function returns true, then the tree ceases to be walked, and foreach_iter() returns.
+   *
+   * For example: bool on_foreach_iter(const Gtk::TreeModel::iterator& iter);
    */
   typedef sigc::slot<bool(const TreeModel::iterator&)> SlotForeachIter;
 
-  /** Calls a callback slot on each node in the model in a depth-first fashion.
+  /** Calls a callback of type @link Gtk::TreeModel::SlotForeachIter
+   * SlotForeachIter @endlink on each node in the model in a depth-first
+   * fashion.
+   *
    * If the callback function returns true, then the tree ceases to be walked, and foreach_iter() returns.
    *
    * @param slot The function to call for each selected node.
    */
   void foreach_iter(const SlotForeachIter& slot);
 
-  /** For example,
-   * void on_foreach(const Gtk::TreeModel::Path& path);
+  /** The type of callback slot used by foreach_path().
+   *
+   * For example: bool on_foreach_path(const Gtk::TreeModel::Path& path);
    *
    * If the callback function returns true, then the tree ceases to be walked, and foreach_path() returns.
    */
   typedef sigc::slot<bool(const TreeModel::Path&)> SlotForeachPath;
 
-  /** Calls a callback slot on each node in the model in a depth-first fashion.
+  /** Calls a callback of type @link Gtk::TreeModel::SlotForeachPath
+   * SlotForeachPath @endlink on each node in the model in a depth-first
+   * fashion.
+   *
    * If the callback function returns true, then the tree ceases to be walked, and foreach_path() returns.
    *
    * @param slot The function to call for each selected node.
    */
   void foreach_path(const SlotForeachPath& slot);
 
-  /** For example,
-   * void on_foreach(const Gtk::TreeModel::Path& path, const Gtk::TreeModel::iterator& iter);
+  /** The type of callback slot used by foreach().
+   *
+   * For example: bool on_foreach(const Gtk::TreeModel::Path& path, const Gtk::TreeModel::iterator& iter);
    *
    * If the callback function returns true, then the tree ceases to be walked, and foreach() returns.
    */
   typedef sigc::slot<bool(const TreeModel::Path&, const TreeModel::iterator&)> SlotForeachPathAndIter;
 
-  /** Calls a callback slot on each node in the model in a depth-first fashion.
+  /** Calls a callback of type @link Gtk::TreeModel::SlotForeachPathAndIter
+   * SlotForeachPathAndIter @endlink on each node in the model in a depth-first
+   * fashion.
+   *
    * If the callback function returns true, then the tree ceases to be walked, and foreach() returns.
    *
    * @param slot The function to call for each selected node.