[gtkmm/gtkmm-3-22] TreeModel: Improve docs of foreach*() functions

[Daniel Boles <dboles src gnome org>]

commit 0d05bc4a49e3c9e216dd4aa2ae1d9c310d5cd795
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
    • Use the actual function name in each case, instead of always foreach()

 gtk/src/treemodel.hg |   48 +++++++++++++++++++++++++++++++++---------------
 1 files changed, 33 insertions(+), 15 deletions(-)
---
diff --git a/gtk/src/treemodel.hg b/gtk/src/treemodel.hg
index 799f39a..0aae94c 100644
--- a/gtk/src/treemodel.hg
+++ b/gtk/src/treemodel.hg
@@ -147,43 +147,61 @@ _DEPRECATE_IFDEF_END
 
   _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() returns.
+   * 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.
-   * If the callback function returns true, then the tree ceases to be walked, and foreach() returns.
+  /** 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() returns.
+   * 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.
-   * If the callback function returns true, then the tree ceases to be walked, and foreach() returns.
+  /** 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.
+   * 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.
-   * If the callback function returns true, then the tree ceases to be walked, and foreach() returns.
+  /** 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.
    */