[gtkmm] Gtk::IconView: Mark output parameters in Doxygen comments

[Kjell Ahlstedt <kjellahl src gnome org>]

commit 473cbdad0615a3a2c689cb6e11298d391112b967
Author: Kjell Ahlstedt <kjell ahlstedt bredband net>
Date:   Mon Mar 6 16:51:10 2017 +0100

    Gtk::IconView: Mark output parameters in Doxygen comments

 gtk/src/iconview.hg |   86 +++++++++++++++++++++++++--------------------------
 1 files changed, 42 insertions(+), 44 deletions(-)
---
diff --git a/gtk/src/iconview.hg b/gtk/src/iconview.hg
index 3274d6a..ad6fc99 100644
--- a/gtk/src/iconview.hg
+++ b/gtk/src/iconview.hg
@@ -109,9 +109,8 @@ public:
    *
    * @param x The x position to be identified.
    * @param y The y position to be identified.
-   * @param path The path.
-   * @param cell The renderer responsible for the cell at (@a x, @a y).
-   *
+   * @param[out] path The path.
+   * @param[out] cell The renderer responsible for the cell at (@a x, @a y).
    * @result true if an item exists at the specified position.
    *
    * @newin{2,6}
@@ -122,8 +121,7 @@ public:
    *
    * @param x The x position to be identified.
    * @param y The y position to be identified.
-   * @param path The path.
-   *
+   * @param[out] path The path.
    * @result true if an item exists at the specified position.
    *
    * @newin{2,6}
@@ -134,8 +132,7 @@ public:
    *
    * @param x The x position to be identified.
    * @param y The y position to be identified.
-   * @param cell The renderer responsible for the cell at (@a x, @a y).
-   *
+   * @param[out] cell The renderer responsible for the cell at (@a x, @a y).
    * @result true if an item exists at the specified position.
    *
    * @newin{2,6}
@@ -143,6 +140,13 @@ public:
   bool get_item_at_pos(int x, int y, CellRenderer*& cell) const;
   _IGNORE(gtk_icon_view_get_item_at_pos)
 
+  /** Sets @a start_path and @a end_path to be the first and last visible path.
+   * Note that there may be invisible paths in between.
+   *
+   * @param[out] start_path Return location for start of region.
+   * @param[out] end_path Return location for end of region.
+   * @result <tt>true</tt> if valid paths were placed in @a start_path and @a end_path.
+   */
   bool get_visible_range(TreeModel::Path& start_path, TreeModel::Path& end_path) const;
   _IGNORE(gtk_icon_view_get_visible_range)
 
@@ -152,7 +156,7 @@ public:
   /** For instance,
    * void on_foreach(const Gtk::TreeModel::Path& path);
    */
-  typedef sigc::slot<void(const TreeModel::Path&)> SlotForeach;
+  using SlotForeach = sigc::slot<void(const TreeModel::Path&)>;
 
   /** Calls a function for each selected icon. Note that the model or
   * selection cannot be modified from within this function.
@@ -195,15 +199,14 @@ public:
   _WRAP_METHOD(void unselect_all(), gtk_icon_view_unselect_all)
   _WRAP_METHOD(void item_activated(const TreeModel::Path& path),  gtk_icon_view_item_activated)
 
-  //TODO: Add a version with no cell parameter.
   _WRAP_METHOD(void set_cursor(const TreeModel::Path& path, CellRenderer& cell{?}, bool start_editing), 
gtk_icon_view_set_cursor)
 
   /** Fills in @a path and @a cell with the current cursor path and cell.
    * If the cursor isn't currently set, then @a path will be empty.
-   * If no cell currently has focus, then @a cell will be NULL.
+   * If no cell currently has focus, then @a cell will be nullptr.
    *
-   * @param path The current cursor path.
-   * @param cell The current focus cell.
+   * @param[out] path The current cursor path.
+   * @param[out] cell The current focus cell.
    * @result true if the cursor is set.
    *
    * @newin{2,8}
@@ -212,9 +215,9 @@ public:
 
   /** Fills in @a path and @a cell with the current cursor path and cell.
    * If the cursor isn't currently set, then @a path will be empty.
-   * If no cell currently has focus, then @a cell will be NULL.
+   * If no cell currently has focus, then @a cell will be nullptr.
    *
-   * @param path The current cursor path.
+   * @param[out] path The current cursor path.
    * @result true if the cursor is set.
    *
    * @newin{2,8}
@@ -223,9 +226,9 @@ public:
 
   /** Fills in @a path and @a cell with the current cursor path and cell.
    * If the cursor isn't currently set, then @a path will be empty.
-   * If no cell currently has focus, then @a cell will be NULL.
+   * If no cell currently has focus, then @a cell will be nullptr.
    *
-   * @param cell The current focus cell.
+   * @param[out] cell The current focus cell.
    * @result true if the cursor is set.
    *
    * @newin{2,8}
@@ -264,13 +267,12 @@ public:
 
 
 /* These are useful to implement your own custom stuff. */
-  //TODO: Discover what arguments are output arguments:
   _WRAP_METHOD(void set_drag_dest_item(const TreeModel::Path& path, IconViewDropPosition pos), 
gtk_icon_view_set_drag_dest_item)
 
   /** Gets information about the item that is highlighted for feedback.
    *
-   * @param path The highlighted item.
-   * @param pos The drop position.
+   * @param[out] path The highlighted item.
+   * @param[out] pos The drop position.
    *
    * @newin{2,10}
    */
@@ -278,7 +280,7 @@ public:
 
   /** Gets information about the item that is highlighted for feedback.
    *
-   * @param path The highlighted item.
+   * @param[out] path The highlighted item.
    *
    * @newin{2,10}
    */
@@ -286,7 +288,7 @@ public:
 
   /** Gets information about the item that is highlighted for feedback.
    *
-   * @param pos The drop position.
+   * @param[out] pos The drop position.
    *
    * @newin{2,10}
    */
@@ -297,9 +299,9 @@ public:
    *
    * @param drag_x The position to determine the destination item for.
    * @param drag_y the position to determine the destination item for.
-   * @param path The path of the item.
-   * @param pos: The drop position.
-   * @result whether there is an item at the given position.
+   * @param[out] path The path of the item.
+   * @param[out] pos The drop position.
+   * @result Whether there is an item at the given position.
    *
    * @newin{2,10}
    */
@@ -309,8 +311,8 @@ public:
    *
    * @param drag_x The position to determine the destination item for.
    * @param drag_y the position to determine the destination item for.
-   * @param path The path of the item.
-   * @result whether there is an item at the given position.
+   * @param[out] path The path of the item.
+   * @result Whether there is an item at the given position.
    *
    * @newin{2,10}
    */
@@ -320,8 +322,8 @@ public:
    *
    * @param drag_x The position to determine the destination item for.
    * @param drag_y the position to determine the destination item for.
-   * @param pos: The drop position.
-   * @result whether there is an item at the given position.
+   * @param[out] pos The drop position.
+   * @result Whether there is an item at the given position.
    *
    * @newin{2,10}
    */
@@ -350,13 +352,7 @@ public:
    */
   void set_tooltip_cell(const Glib::RefPtr<Tooltip>& tooltip, const TreeModel::Path& path);
 
-  /**
-   * @param x: the x coordinate (relative to widget coordinates)
-   * @param y: the y coordinate (relative to widget coordinates)
-   * @param keyboard_tip: whether this is a keyboard tooltip or not
-   * @param path: a reference to receive a Gtk::TreePath
-   *
-   * This function is supposed to be used in a Gtk::Widget::query-tooltip
+  /** This function is supposed to be used in a Gtk::Widget::query-tooltip
    * signal handler for Gtk::IconView. The x, y and keyboard_tip values
    * which are received in the signal handler, should be passed to this
    * function without modification.
@@ -368,7 +364,11 @@ public:
    * that row and the corresponding model. x and y will always be converted
    * to be relative to IconView's bin_window if keyboard_tooltip is false.
    *
-   * Return value: whether or not the given tooltip context points to a item.
+   * @param[in,out] x The x coordinate (relative to widget coordinates)
+   * @param[in,out] y The y coordinate (relative to widget coordinates)
+   * @param keyboard_tip Whether this is a keyboard tooltip or not
+   * @param[out] path A reference to receive a Gtk::TreePath
+   * @result Whether or not the given tooltip context points to an item.
    *
    * @newin{2,12}
    */
@@ -376,13 +376,7 @@ public:
                                 bool keyboard_tip,
                                 TreeModel::Path& path);
 
-  /**
-   * @param x: the x coordinate (relative to widget coordinates)
-   * @param y: the y coordinate (relative to widget coordinates)
-   * @param keyboard_tip: whether this is a keyboard tooltip or not
-   * @param iter: a pointer to receive a Gtk::TreeModel::iterator
-   *
-   * This function is supposed to be used in a Gtk::Widget::query-tooltip
+  /** This function is supposed to be used in a Gtk::Widget::query-tooltip
    * signal handler for Gtk::IconView. The x, y and keyboard_tip values
    * which are received in the signal handler, should be passed to this
    * function without modification.
@@ -394,7 +388,11 @@ public:
    * that row and the corresponding model. x and y will always be converted
    * to be relative to IconView's bin_window if keyboard_tooltip is false.
    *
-   * Return value: whether or not the given tooltip context points to a item.
+   * @param[in,out] x The x coordinate (relative to widget coordinates)
+   * @param[in,out] y The y coordinate (relative to widget coordinates)
+   * @param keyboard_tip Whether this is a keyboard tooltip or not
+   * @param[out] iter A reference to receive a Gtk::TreeModel::iterator
+   * @result Whether or not the given tooltip context points to an item.
    *
    * @newin{2,12}
    */