[gtkmm] Stock ID stuff needs documentation (bgo#506885)

[Johannes Schmid <jhs src gnome org>]

commit 1270bdfb49d4f3bb1cdac9f1ee2082d1b5218089
Author: Johannes Schmid <jhs gnome org>
Date:   Tue Apr 28 09:27:55 2009 +0200

    Stock ID stuff needs documentation (bgo#506885)
    
    Document as much as there is information available
    from the Gtk+ documentation
---
 ChangeLog           |   11 ++++++++++-
 gtk/gtkmm/stock.h   |   34 +++++++++++++++++++++++++++++++++-
 gtk/gtkmm/stockid.h |   43 +++++++++++++++++++++++++++++++++++++++++--
 gtk/src/iconset.hg  |    9 +++++++++
 4 files changed, 93 insertions(+), 4 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 2c4f1a0..c4355db 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,9 +1,18 @@
+2009-04-28  Johannes Schmid <jschmid openismus com>
+
+  * gtk/gtkmm/stock.h:
+  * gtk/gtkmm/stockitem.h:
+  * gtk/src/iconset.hg:
+  506885 â?? Stock ID stuff needs documentation
+  
+  Document as much as there is information available from the Gtk+ documentation
+
 2009-04-27  Johannes Schmid <jschmid openismus com>
 
   * gtk/src/statusicon.ccg:
   Reference the returned statusicon because the RefPtr becomes invalid
   otherwise (#575268)
-
+  
 2009-04-18  Daniel Elstner  <danielk openismus com>
 
 	* docs/reference/images/stock: Add these stock images to the repository for
diff --git a/gtk/gtkmm/stock.h b/gtk/gtkmm/stock.h
index 6a49bf1..51842f6 100644
--- a/gtk/gtkmm/stock.h
+++ b/gtk/gtkmm/stock.h
@@ -47,6 +47,9 @@ namespace Gtk
  */
 struct BuiltinStockID
 {
+  /**
+   * The text representation of the stock id, usually something like "gtk-about".
+   */
   const char* id;
 };
 
@@ -178,13 +181,42 @@ extern GTKMM_API const Gtk::BuiltinStockID ZOOM_FIT;         /*!< @image html gt
 extern GTKMM_API const Gtk::BuiltinStockID ZOOM_IN;          /*!< @image html gtk-zoom-in.png             */
 extern GTKMM_API const Gtk::BuiltinStockID ZOOM_OUT;         /*!< @image html gtk-zoom-out.png            */
 
-
+/** Add a stock item to the list of registered stock items.
+ * @param item StockItem to register.
+ * 
+ * If an item already exists with the same stock ID the old item gets replaced. 
+ */
 void add(const Gtk::StockItem& item);
 
+/** Fills item with the registered values for stock_id.
+  * @param stock_id StockID to search for.
+  * @param item item to fill in case stockid was found.
+  *
+  * @return <tt>true</tt> if the item was found - <tt>false</tt> otherwise.
+  */
 bool lookup(const Gtk::StockID& stock_id, Gtk::StockItem& item);
+
+/** See IconSet::lookup_default()
+  * @param stock_id StockID to search for.
+  * @param iconset to fill.
+  *
+  * @return <tt>true</tt> if the item was found - <tt>false</tt> otherwise.
+  */
 bool lookup(const Gtk::StockID& stock_id, Gtk::IconSet& iconset);
+
+/** Receive an Image of the registered stock id with the correct size.
+  * @param stock_id StockID to search for.
+  * @param size: IconSize of the desired Image.
+  * @param image: Image to fill.
+  *
+  * @return <tt>true</tt> if the item was found - <tt>false</tt> otherwise
+  */  
 bool lookup(const Gtk::StockID& stock_id, Gtk::IconSize size, Gtk::Image& image);
 
+/** Retrieves a list of all known stock IDs added to an IconFactory or registered with Stock::add().
+  *
+  * @return list of all known stock IDs.
+  */
 Glib::SListHandle<Gtk::StockID,Gtk::StockID_Traits> get_ids();
 
 } // namespace Stock
diff --git a/gtk/gtkmm/stockid.h b/gtk/gtkmm/stockid.h
index caf109a..e238aaf 100644
--- a/gtk/gtkmm/stockid.h
+++ b/gtk/gtkmm/stockid.h
@@ -35,21 +35,60 @@ struct BuiltinStockID;
 class StockID
 {
 public:
+  /** Create an empty StockID
+   */
   StockID(); //TODO: This was added for Action::Action, but there might be a better way to do this.
+
+  /** Create a StockID from one of the build-in stock ids.
+   *
+   * See also Gtk::BuildinStockID.
+   */
   StockID(const BuiltinStockID& id);
+
+  /** Create a StockID from its string representation.
+   * @param id string representation of the stock id. Usually something like "gtk-about".
+   */
   explicit StockID(const Glib::ustring& id);
-  explicit StockID(const char* id); // id can be 0
+
+  /** Create a StockID from its string representation.
+   * @param id string representation of the stock id. Usually something like "gtk-about".
+   *
+   * If id is 0 an empty StockID will be created.
+   */  
+  explicit StockID(const char* id);
   ~StockID();
 
+  /** Create a StockID as copy from another.
+   * @param other: StockID to copy.
+   */
   StockID(const StockID& other);
+
+  /** Check if the StockIDs are equal.
+   * @param other Another StockID.
+   */
   StockID& operator=(const StockID& other);
 
-  /// Tests whether the StockID is not empty.
+  /** Tests whether the StockID is not empty.
+   */
   operator bool() const;
 
+  /** Check if two StockIDs are equal.
+   * @param rhs Another StockID.
+   *
+   * @return <tt>true</tt> if both ids equal - <tt>false</tt> otherwise.
+   */
   bool equal(const StockID& rhs) const;
 
+  /** Get the string representation of the StockID.
+   *
+   * @return something like "gtk-about".
+   */
   Glib::ustring get_string() const;
+
+  /** Get the string representation as a const gchar*.
+   *
+   * @return string representation as const gchar*.
+   */
   const char*   get_c_str()  const;
 
 protected:
diff --git a/gtk/src/iconset.hg b/gtk/src/iconset.hg
index 44a6c6f..98d8356 100644
--- a/gtk/src/iconset.hg
+++ b/gtk/src/iconset.hg
@@ -57,6 +57,15 @@ public:
 
   Glib::ArrayHandle<IconSize> get_sizes() const;
 
+  /** Looks for an icon in the list of default icon factories.
+   * @param stock_id StockID to search for
+   *
+   * For display to the user, you should use Style::lookup_icon_set() on the Style 
+   * for the widget that will display the icon, instead of using this function directly, 
+   * so that themes are taken into account
+   *
+   * @returns an IconSet
+   */
   static IconSet lookup_default(const Gtk::StockID& stock_id);
 };