[gtk+] Move documentation to inline comments: GtkIconTheme

[Javier Jardón <jjardon src gnome org>]

commit 0dd93537b309d7962938bce6143f7645e5915592
Author: Javier Jardón <jjardon gnome org>
Date:   Thu Apr 14 22:07:29 2011 +0100

    Move documentation to inline comments: GtkIconTheme

 docs/reference/gtk/tmpl/.gitignore        |    1 +
 docs/reference/gtk/tmpl/gtkicontheme.sgml |  502 -----------------------------
 gtk/gtkicontheme.c                        |   86 +++++
 gtk/gtkicontheme.h                        |   22 ++
 4 files changed, 109 insertions(+), 502 deletions(-)
---
diff --git a/docs/reference/gtk/tmpl/.gitignore b/docs/reference/gtk/tmpl/.gitignore
index 6ad4cb7..8c5ba90 100644
--- a/docs/reference/gtk/tmpl/.gitignore
+++ b/docs/reference/gtk/tmpl/.gitignore
@@ -53,6 +53,7 @@ gtkhscale.sgml
 gtkhscrollbar.sgml
 gtkhseparator.sgml
 gtkiconfactory.sgml
+gtkicontheme.sgml
 gtkiconview.sgml
 gtkimagemenuitem.sgml
 gtkimcontext.sgml
diff --git a/gtk/gtkicontheme.c b/gtk/gtkicontheme.c
index db65d51..1845adb 100644
--- a/gtk/gtkicontheme.c
+++ b/gtk/gtkicontheme.c
@@ -49,6 +49,92 @@
 #include "gtksettings.h"
 #include "gtkprivate.h"
 
+
+/**
+ * SECTION:gtkicontheme
+ * @Short_description: Looking up icons by name
+ * @Title: GtkIconTheme
+ *
+ * #GtkIconTheme provides a facility for looking up icons by name
+ * and size. The main reason for using a name rather than simply
+ * providing a filename is to allow different icons to be used
+ * depending on what <firstterm>icon theme</firstterm> is selected
+ * by the user. The operation of icon themes on Linux and Unix
+ * follows the <ulink
+ * url="http://www.freedesktop.org/Standards/icon-theme-spec";>Icon
+ * Theme Specification</ulink>. There is a default icon theme,
+ * named <literal>hicolor</literal> where applications should install
+ * their icons, but more additional application themes can be
+ * installed as operating system vendors and users choose.
+ *
+ * Named icons are similar to the <xref linkend="gtk3-Themeable-Stock-Images"/>
+ * facility, and the distinction between the two may be a bit confusing.
+ * A few things to keep in mind:
+ * <itemizedlist>
+ * <listitem>
+ * Stock images usually are used in conjunction with
+ * <xref linkend="gtk3-Stock-Items"/>, such as %GTK_STOCK_OK or
+ * %GTK_STOCK_OPEN. Named icons are easier to set up and therefore
+ * are more useful for new icons that an application wants to
+ * add, such as application icons or window icons.
+ * </listitem>
+ * <listitem>
+ * Stock images can only be loaded at the symbolic sizes defined
+ * by the #GtkIconSize enumeration, or by custom sizes defined
+ * by gtk_icon_size_register(), while named icons are more flexible
+ * and any pixel size can be specified.
+ * </listitem>
+ * <listitem>
+ * Because stock images are closely tied to stock items, and thus
+ * to actions in the user interface, stock images may come in
+ * multiple variants for different widget states or writing
+ * directions.
+ * </listitem>
+ * </itemizedlist>
+ * A good rule of thumb is that if there is a stock image for what
+ * you want to use, use it, otherwise use a named icon. It turns
+ * out that internally stock images are generally defined in
+ * terms of one or more named icons. (An example of the
+ * more than one case is icons that depend on writing direction;
+ * %GTK_STOCK_GO_FORWARD uses the two themed icons
+ * "gtk-stock-go-forward-ltr" and "gtk-stock-go-forward-rtl".)
+ *
+ * In many cases, named themes are used indirectly, via #GtkImage
+ * or stock items, rather than directly, but looking up icons
+ * directly is also simple. The #GtkIconTheme object acts
+ * as a database of all the icons in the current theme. You
+ * can create new #GtkIconTheme objects, but its much more
+ * efficient to use the standard icon theme for the #GdkScreen
+ * so that the icon information is shared with other people
+ * looking up icons. In the case where the default screen is
+ * being used, looking up an icon can be as simple as:
+ * <informalexample>
+ * <programlisting>
+ * GError *error = NULL;
+ * GtkIconTheme *icon_theme;
+ * GdkPixbuf *pixbuf;
+ *
+ * icon_theme = gtk_icon_theme_get_default ();
+ * pixbuf = gtk_icon_theme_load_icon (icon_theme,
+ *                                    "my-icon-name", // icon name
+ *                                    48, // size
+ *                                    0,  // flags
+ *                                    &error);
+ * if (!pixbuf)
+ *   {
+ *     g_warning ("Couldn't load icon: &percnt;s", error->message);
+ *     g_error_free (error);
+ *   }
+ * else
+ *   {
+ *     // Use the pixbuf
+ *     g_object_unref (pixbuf);
+ *   }
+ * </programlisting>
+ * </informalexample>
+ */
+
+
 #define DEFAULT_THEME_NAME "hicolor"
 
 typedef enum
diff --git a/gtk/gtkicontheme.h b/gtk/gtkicontheme.h
index 607bdf0..6d3ea2d 100644
--- a/gtk/gtkicontheme.h
+++ b/gtk/gtkicontheme.h
@@ -40,11 +40,28 @@ G_BEGIN_DECLS
 #define GTK_IS_ICON_THEME_CLASS(klass)  (G_TYPE_CHECK_CLASS_TYPE ((klass), GTK_TYPE_ICON_THEME))
 #define GTK_ICON_THEME_GET_CLASS(obj)   (G_TYPE_INSTANCE_GET_CLASS ((obj), GTK_TYPE_ICON_THEME, GtkIconThemeClass))
 
+/**
+ * GtkIconInfo:
+ *
+ * Contains information found when looking up an icon in
+ * an icon theme.
+ */
 typedef struct _GtkIconInfo         GtkIconInfo;
 typedef struct _GtkIconTheme        GtkIconTheme;
 typedef struct _GtkIconThemeClass   GtkIconThemeClass;
 typedef struct _GtkIconThemePrivate GtkIconThemePrivate;
 
+/**
+ * GtkIconTheme:
+ *
+ * Acts as a database of information about an icon theme.
+ * Normally, you retrieve the icon theme for a particular
+ * screen using gtk_icon_theme_get_for_screen() and it
+ * will contain information about current icon theme for
+ * that screen, but you can also create a new #GtkIconTheme
+ * object and set the icon theme name explicitely using
+ * gtk_icon_theme_set_custom_theme().
+ */
 struct _GtkIconTheme
 {
   /*< private >*/
@@ -94,6 +111,11 @@ typedef enum
   GTK_ICON_LOOKUP_FORCE_SIZE       = 1 << 4
 } GtkIconLookupFlags;
 
+/**
+ * GTK_ICON_THEME_ERROR:
+ *
+ * The #GQuark used for #GtkIconThemeError errors.
+ */
 #define GTK_ICON_THEME_ERROR gtk_icon_theme_error_quark ()
 
 /**