[gtk+/gtk-style-context] Add theming docs



commit 83dd4cf1c18b62b519e385f0c47a8915fce68c3c
Author: Carlos Garnacho <carlosg gnome org>
Date:   Tue Oct 19 10:59:46 2010 +0200

    Add theming docs
    
    Both API and file format is documented, there's still missing
    a migration doc though.

 docs/reference/gtk/Makefile.am       |    3 +
 docs/reference/gtk/gtk-docs.sgml     |    9 +
 docs/reference/gtk/gtk3-sections.txt |  242 ++++++++++++
 docs/reference/gtk/gtk3.types        |    4 +
 gtk/gtk.h                            |    1 +
 gtk/gtkanimationdescription.h        |    2 +-
 gtk/gtkcontainer.c                   |   10 +
 gtk/gtkcssprovider.c                 |  414 +++++++++++++++++++++
 gtk/gtkcssprovider.h                 |    8 +-
 gtk/gtkenums.h                       |   31 ++
 gtk/gtkstylecontext.c                |  672 ++++++++++++++++++++++++++++++++-
 gtk/gtkstylecontext.h                |    8 +-
 gtk/gtkstyleprovider.c               |   52 +++-
 gtk/gtkstyleprovider.h               |   14 +-
 gtk/gtkstyleset.c                    |  154 ++++++++
 gtk/gtkstyleset.h                    |    8 +-
 gtk/gtksymboliccolor.c               |  164 ++++++++-
 gtk/gtksymboliccolor.h               |    4 +-
 gtk/gtkthemingengine.c               |  211 +++++++++++-
 gtk/gtkthemingengine.h               |   28 ++-
 gtk/gtkwidget.c                      |   19 +
 gtk/gtkwidgetpath.c                  |  383 +++++++++++++++++++-
 gtk/gtkwidgetpath.h                  |    2 +-
 23 files changed, 2387 insertions(+), 56 deletions(-)
---
diff --git a/docs/reference/gtk/Makefile.am b/docs/reference/gtk/Makefile.am
index 4f71a8f..226298b 100644
--- a/docs/reference/gtk/Makefile.am
+++ b/docs/reference/gtk/Makefile.am
@@ -22,6 +22,8 @@ CFILE_GLOB=$(top_srcdir)/gtk/*.c
 # Header files to ignore when scanning
 IGNORE_HFILES=				\
 	fnmatch.h			\
+	gtk9slice.h			\
+	gtkanimationdescription.h	\
 	gtkdebug.h			\
 	gtkbuilderprivate.h		\
 	gtkdndcursors.h			\
@@ -77,6 +79,7 @@ IGNORE_HFILES=				\
 	gtktexttagprivate.h		\
 	gtktexttypes.h			\
 	gtktextutil.h			\
+	gtktimeline.h			\
 	gtkthemes.h			\
 	gtktrayicon.h			\
 	gtktreedatalist.h		\
diff --git a/docs/reference/gtk/gtk-docs.sgml b/docs/reference/gtk/gtk-docs.sgml
index 60bf1af..a6efcef 100644
--- a/docs/reference/gtk/gtk-docs.sgml
+++ b/docs/reference/gtk/gtk-docs.sgml
@@ -145,6 +145,15 @@ that is, GUI components such as #GtkButton or #GtkTextView.
     <xi:include href="xml/filesystem.xml" />
   </part>
 
+  <part id="theming">
+    <title>Theming in GTK+</title>
+    <xi:include href="xml/gtkwidgetpath.xml" />
+    <xi:include href="xml/gtkstyleprovider.xml" />
+    <xi:include href="xml/gtkstylecontext.xml" />
+    <xi:include href="xml/gtkcssprovider.xml" />
+    <xi:include href="xml/gtkthemingengine.xml" />
+  </part>
+
   <part id="gtkobjects">
     <title>GTK+ Widgets and Objects</title>
 
diff --git a/docs/reference/gtk/gtk3-sections.txt b/docs/reference/gtk/gtk3-sections.txt
index ad27a06..c49b319 100644
--- a/docs/reference/gtk/gtk3-sections.txt
+++ b/docs/reference/gtk/gtk3-sections.txt
@@ -847,6 +847,7 @@ gtk_container_set_resize_mode
 gtk_container_check_resize
 gtk_container_foreach
 gtk_container_get_children
+gtk_container_get_path_for_child
 gtk_container_set_reallocate_redraws
 gtk_container_get_focus_child
 gtk_container_set_focus_child
@@ -4912,6 +4913,11 @@ gtk_widget_get_requisition
 gtk_widget_device_is_shadowed
 
 <SUBSECTION>
+gtk_widget_get_path
+gtk_widget_get_style_context
+gtk_widget_reset_style
+
+<SUBSECTION>
 gtk_requisition_new
 gtk_requisition_copy
 gtk_requisition_free
@@ -5177,6 +5183,242 @@ GTK_CHECK_VERSION
 </SECTION>
 
 <SECTION>
+<FILE>gtkwidgetpath</FILE>
+<TITLE>GtkWidgetPath</TITLE>
+GtkWidgetPath
+gtk_widget_path_append_type
+gtk_widget_path_copy
+gtk_widget_path_free
+gtk_widget_path_get_widget_type
+gtk_widget_path_has_parent
+gtk_widget_path_is_type
+gtk_widget_path_iter_add_class
+gtk_widget_path_iter_add_region
+gtk_widget_path_iter_clear_classes
+gtk_widget_path_iter_clear_regions
+gtk_widget_path_iter_get_name
+gtk_widget_path_iter_get_widget_type
+gtk_widget_path_iter_has_class
+gtk_widget_path_iter_has_name
+gtk_widget_path_iter_has_qclass
+gtk_widget_path_iter_has_qname
+gtk_widget_path_iter_has_qregion
+gtk_widget_path_iter_has_region
+gtk_widget_path_iter_list_classes
+gtk_widget_path_iter_list_regions
+gtk_widget_path_iter_remove_class
+gtk_widget_path_iter_remove_region
+gtk_widget_path_iter_set_name
+gtk_widget_path_iter_set_widget_type
+gtk_widget_path_length
+gtk_widget_path_new
+gtk_widget_path_prepend_type
+</SECTION>
+
+<SECTION>
+<FILE>gtkstyleprovider</FILE>
+<TITLE>GtkStyleProvider</TITLE>
+GtkStyleProviderIface
+GtkStyleProvider
+GTK_STYLE_PROVIDER_PRIORITY_APPLICATION
+GTK_STYLE_PROVIDER_PRIORITY_DEFAULT
+GTK_STYLE_PROVIDER_PRIORITY_FALLBACK
+GTK_STYLE_PROVIDER_PRIORITY_SETTINGS
+GTK_STYLE_PROVIDER_PRIORITY_USER
+gtk_style_provider_get_icon_factory
+gtk_style_provider_get_style
+gtk_style_provider_get_style_property
+<SUBSECTION Standard>
+GTK_TYPE_STYLE_PROVIDER
+GTK_STYLE_PROVIDER
+GTK_IS_STYLE_PROVIDER
+GTK_STYLE_PROVIDER_GET_IFACE
+<SUBSECTION Private>
+gtk_style_provider_get_type
+</SECTION>
+
+<SECTION>
+<FILE>gtksymboliccolor</FILE>
+<TITLE>GtkSymbolicColor</TITLE>
+GtkSymbolicColor
+GtkGradient
+gtk_symbolic_color_new_literal
+gtk_symbolic_color_new_mix
+gtk_symbolic_color_new_name
+gtk_symbolic_color_new_shade
+gtk_symbolic_color_resolve
+gtk_symbolic_color_ref
+gtk_symbolic_color_unref
+gtk_gradient_new_linear
+gtk_gradient_new_radial
+gtk_gradient_add_color_stop
+gtk_gradient_resolve
+gtk_gradient_ref
+gtk_gradient_unref
+<SUBSECTION Standard>
+GTK_TYPE_GRADIENT
+GTK_TYPE_SYMBOLIC_COLOR
+<SUBSECTION Private>
+gtk_symbolic_color_get_type
+gtk_gradient_get_type
+</SECTION>
+
+<SECTION>
+<FILE>gtkstyleset</FILE>
+<TITLE>GtkStyleSet</TITLE>
+GtkStyleSet
+gtk_style_set_clear
+gtk_style_set_get
+gtk_style_set_get_property
+gtk_style_set_get_valist
+gtk_style_set_lookup_color
+gtk_style_set_lookup_property
+gtk_style_set_map_color
+gtk_style_set_merge
+gtk_style_set_new
+gtk_style_set_register_property
+gtk_style_set_set
+gtk_style_set_set_property
+gtk_style_set_set_valist
+gtk_style_set_unset_property
+<SUBSECTION Standard>
+GTK_TYPE_STYLE_SET
+GTK_IS_STYLE_SET
+GTK_IS_STYLE_SET_CLASS
+GTK_STYLE_SET
+GTK_STYLE_SET_CLASS
+GTK_STYLE_SET_GET_CLASS
+<SUBSECTION Private>
+gtk_style_set_get_type
+</SECTION>
+
+<SECTION>
+<FILE>gtkstylecontext</FILE>
+<TITLE>GtkStyleContext</TITLE>
+GtkStyleContext
+gtk_style_context_add_provider
+gtk_style_context_add_provider_for_screen
+gtk_style_context_get
+gtk_style_context_get_direction
+gtk_style_context_get_junction_sides
+gtk_style_context_get_path
+gtk_style_context_get_property
+gtk_style_context_get_screen
+gtk_style_context_get_state
+gtk_style_context_get_style
+gtk_style_context_get_style_property
+gtk_style_context_get_style_valist
+gtk_style_context_get_valist
+gtk_style_context_has_class
+gtk_style_context_has_region
+gtk_style_context_invalidate
+gtk_style_context_is_state_set
+gtk_style_context_list_classes
+gtk_style_context_list_regions
+gtk_style_context_lookup_color
+gtk_style_context_lookup_icon_set
+gtk_style_context_notify_state_change
+gtk_style_context_pop_animatable_region
+gtk_style_context_push_animatable_region
+gtk_style_context_remove_provider
+gtk_style_context_remove_provider_for_screen
+gtk_style_context_reset_widgets
+gtk_style_context_restore
+gtk_style_context_save
+gtk_style_context_set_class
+gtk_style_context_set_direction
+gtk_style_context_set_junction_sides
+gtk_style_context_set_path
+gtk_style_context_set_region
+gtk_style_context_set_screen
+gtk_style_context_set_state
+gtk_style_context_state_transition_start
+gtk_style_context_state_transition_stop
+gtk_style_context_state_transition_update
+gtk_style_context_unset_class
+gtk_style_context_unset_region
+
+<SUBSECTION>
+gtk_render_arrow
+gtk_render_background
+gtk_render_check
+gtk_render_expander
+gtk_render_extension
+gtk_render_focus
+gtk_render_frame
+gtk_render_frame_gap
+gtk_render_handle
+gtk_render_layout
+gtk_render_line
+gtk_render_option
+gtk_render_progress
+gtk_render_slider
+
+<SUBSECTION Standard>
+GTK_TYPE_STYLE_CONTEXT
+GTK_STYLE_CONTEXT
+GTK_STYLE_CONTEXT_CLASS
+GTK_STYLE_CONTEXT_GET_CLASS
+GTK_IS_STYLE_CONTEXT
+GTK_IS_STYLE_CONTEXT_CLASS
+<SUBSECTION Private>
+gtk_style_context_get_type
+</SECTION>
+
+<SECTION>
+<FILE>gtkcssprovider</FILE>
+<TITLE>GtkCssProvider</TITLE>
+GtkCssProvider
+gtk_css_provider_get_default
+gtk_css_provider_get_named
+gtk_css_provider_load_from_data
+gtk_css_provider_load_from_file
+gtk_css_provider_load_from_path
+gtk_css_provider_new
+<SUBSECTION Standard>
+GTK_TYPE_CSS_PROVIDER
+GTK_CSS_PROVIDER
+GTK_CSS_PROVIDER_CLASS
+GTK_CSS_PROVIDER_GET_CLASS
+GTK_IS_CSS_PROVIDER
+GTK_IS_CSS_PROVIDER_CLASS
+<SUBSECTION Private>
+gtk_css_provider_get_type
+</SECTION>
+
+<SECTION>
+<FILE>gtkthemingengine</FILE>
+<TITLE>GtkThemingEngine</TITLE>
+GtkThemingEngineClass
+GtkThemingEngine
+gtk_theming_engine_get
+gtk_theming_engine_get_direction
+gtk_theming_engine_get_junction_sides
+gtk_theming_engine_get_path
+gtk_theming_engine_get_property
+gtk_theming_engine_get_screen
+gtk_theming_engine_get_state
+gtk_theming_engine_get_style
+gtk_theming_engine_get_style_property
+gtk_theming_engine_get_style_valist
+gtk_theming_engine_get_valist
+gtk_theming_engine_has_class
+gtk_theming_engine_has_region
+gtk_theming_engine_is_state_set
+gtk_theming_engine_load
+gtk_theming_engine_register_property
+<SUBSECTION Standard>
+GTK_THEMING_ENGINE
+GTK_THEMING_ENGINE_CLASS
+GTK_THEMING_ENGINE_GET_CLASS
+GTK_IS_THEMING_ENGINE
+GTK_IS_THEMING_ENGINE_CLASS
+<SUBSECTION Private>
+GTK_TYPE_THEMING_ENGINE
+gtk_theming_engine_get_type
+</SECTION>
+
+<SECTION>
 <FILE>gtkstyle</FILE>
 <TITLE>GtkStyle</TITLE>
 GTK_STYLE_ATTACHED
diff --git a/docs/reference/gtk/gtk3.types b/docs/reference/gtk/gtk3.types
index 86d8d82..0613e5c 100644
--- a/docs/reference/gtk/gtk3.types
+++ b/docs/reference/gtk/gtk3.types
@@ -43,6 +43,7 @@ gtk_color_selection_get_type
 gtk_combo_box_entry_get_type
 gtk_combo_box_get_type
 gtk_container_get_type
+gtk_css_provider_get_type
 gtk_dialog_get_type
 gtk_drawing_area_get_type
 gtk_editable_get_type
@@ -136,6 +137,8 @@ gtk_spinner_get_type
 gtk_statusbar_get_type
 gtk_status_icon_get_type
 gtk_style_get_type
+gtk_style_context_get_type
+gtk_style_provider_get_type
 gtk_table_get_type
 gtk_tearoff_menu_item_get_type
 gtk_text_buffer_get_type
@@ -145,6 +148,7 @@ gtk_text_mark_get_type
 gtk_text_tag_get_type
 gtk_text_tag_table_get_type
 gtk_text_view_get_type
+gtk_theming_engine_get_type
 gtk_toggle_action_get_type
 gtk_toggle_button_get_type
 gtk_toggle_tool_button_get_type
diff --git a/gtk/gtk.h b/gtk/gtk.h
index 303b205..0b71d86 100644
--- a/gtk/gtk.h
+++ b/gtk/gtk.h
@@ -175,6 +175,7 @@
 #include <gtk/gtkstyleprovider.h>
 #include <gtk/gtkstyleset.h>
 #include <gtk/gtkstyle.h>
+#include <gtk/gtksymboliccolor.h>
 #include <gtk/gtktable.h>
 #include <gtk/gtktearoffmenuitem.h>
 #include <gtk/gtktextbuffer.h>
diff --git a/gtk/gtkanimationdescription.h b/gtk/gtkanimationdescription.h
index 14537ed..7770df2 100644
--- a/gtk/gtkanimationdescription.h
+++ b/gtk/gtkanimationdescription.h
@@ -44,4 +44,4 @@ GtkAnimationDescription * gtk_animation_description_from_string (const gchar *st
 
 G_END_DECLS
 
-#endif /* __GTK_ANIMATION_DESC_H__ */
+#endif /* __GTK_ANIMATION_DESCRIPTION_H__ */
diff --git a/gtk/gtkcontainer.c b/gtk/gtkcontainer.c
index 838b460..341cdf0 100644
--- a/gtk/gtkcontainer.c
+++ b/gtk/gtkcontainer.c
@@ -2946,6 +2946,16 @@ _gtk_container_get_reallocate_redraws (GtkContainer *container)
   return container->priv->reallocate_redraws;
 }
 
+/**
+ * gtk_container_get_path_for_child:
+ * @container: a #GtkContainer
+ * @child: a child of @container
+ *
+ * Returns a newly created widget path representing all the widget hierarchy
+ * from the toplevel down to @child (this one not being included).
+ *
+ * Returns: A newly created #GtkWidgetPath
+ **/
 GtkWidgetPath *
 gtk_container_get_path_for_child (GtkContainer *container,
                                   GtkWidget    *child)
diff --git a/gtk/gtkcssprovider.c b/gtk/gtkcssprovider.c
index d4faf88..83f9cad 100644
--- a/gtk/gtkcssprovider.c
+++ b/gtk/gtkcssprovider.c
@@ -30,6 +30,360 @@
 #include "gtk9slice.h"
 #include "gtkcssprovider.h"
 
+/**
+ * SECTION:gtkcssprovider
+ * @Short_description: CSS-like styling for widgets
+ * @Title: GtkCssProvider
+ * @See_also: #GtkStyleContext, #GtkStyleProvider
+ *
+ * #GtkCssProvider is an object implementing #GtkStyleProvider, it is able
+ * to parse CSS-like input in order to style widgets.
+ *
+ * <refsect2 id="gtkcssprovider-selectors">
+ * <title>Widget selectors</title>
+ * <para>
+ * Selectors work in a really similar way than in common CSS, widget object
+ * names act as HTML tags:
+ * </para>
+ * <example>
+ * <title>Widgets in selectors</title>
+ * <programlisting>
+ * /&ast; Theme labels that are descendants of a window &ast;/
+ * GtkWindow GtkLabel {
+ *     background-color: &num;898989;
+ * }
+ *
+ * /&ast; Theme notebooks, and anything that's within these &ast;/
+ * GtkNotebook {
+ *     background-color: &num;a939f0;
+ * }
+ *
+ * /&ast; Theme combo boxes, and entries that
+ *  are direct children of a notebook &ast;/
+ * GtkComboBox,
+ * GtkNotebook > GtkEntry {
+ *     background-color: &num;1209a2;
+ * }
+ *
+ * /&ast; Theme any widget within a GtkBin &ast;/
+ * GtkBin * {
+ *     font-name: Sans 20;
+ * }
+ * </programlisting>
+ * </example>
+ * <para>
+ * Widget names may be matched in CSS as well:
+ * </para>
+ * <example>
+ * <title>Widget names in selectors</title>
+ * <programlisting>
+ * /&ast; Theme a label named title-label &ast;/
+ * GtkLabel&num;title-label {
+ *     font-name: Sans 15;
+ * }
+ *
+ * /&ast; Theme any widget named main-entry &ast;/
+ * &num;main-entry {
+ *     background-color: &num;f0a810;
+ * }
+ * </programlisting>
+ * </example>
+ * <para>
+ * Widgets may also define different classes, so these can be matched
+ * in CSS:
+ * </para>
+ * <example>
+ * <title>Widget names in selectors</title>
+ * <programlisting>
+ * /&ast; Theme all widgets defining the class entry &ast;/
+ * .entry {
+ *     foreground-color: &num;39f1f9;
+ * }
+ *
+ * /&ast; Theme spinbuttons' entry &ast;/
+ * GtkSpinButton.entry {
+ *     foreground-color: &num;900185;
+ * }
+ * </programlisting>
+ * </example>
+ * <para>
+ * Container widgets may define regions, these region names may be
+ * referenced in CSS, it's also possible to apply :nth-child
+ * pseudo-class information if the widget implementation provides
+ * such data.
+ * </para>
+ * <example>
+ * <title>Region names in containers</title>
+ * <programlisting>
+ * /&ast; Theme any label within a notebook &ast;/
+ * GtkNotebook GtkLabel {
+ *     foreground-color: &num;f90192;
+ * }
+ *
+ * /&ast; Theme labels within notebook tabs &ast;/
+ * GtkNotebook tab:nth-child GtkLabel {
+ *     foreground-color: &num;703910;
+ * }
+ *
+ * /&ast; Theme labels in the any first notebook
+ *  tab, both selectors are equivalent &ast;/
+ * GtkNotebook tab:nth-child(first) GtkLabel,
+ * GtkNotebook tab:first-child GtkLabel {
+ *     foreground-color: &num;89d012;
+ * }
+ * </programlisting>
+ * </example>
+ * <para>
+ * Widget states may be matched as pseudoclasses.
+ * Given the needed widget states differ from the
+ * offered pseudoclasses in CSS, some are unsupported,
+ * and some custom ones have been added.
+ * </para>
+ * <example>
+ * <title>Styling specific widget states</title>
+ * <programlisting>
+ * /&ast; Theme active (pressed) buttons &ast;/
+ * GtkButton:active {
+ *     background-color: &num;0274d9;
+ * }
+ *
+ * /&ast; Theme buttons with the mouse pointer on it &ast;/
+ * GtkButton:hover,
+ * GtkButton:prelight {
+ *     background-color: &num;3085a9;
+ * }
+ *
+ * /&ast; Theme insensitive widgets, both are equivalent &ast;/
+ * :insensitive,
+ * *:insensitive {
+ *     background-color: &num;320a91;
+ * }
+ *
+ * /&ast; Theme selection colors in entries &ast;/
+ * GtkEntry:selected {
+ *     background-color: &num;56f9a0;
+ * }
+ *
+ * /&ast; Theme focused labels &ast;/
+ * GtkLabel:focused {
+ *     background-color: &num;b4940f;
+ * }
+ *
+ * /&ast; Theme inconsistent checkbuttons &ast;/
+ * GtkCheckButton:inconsistent {
+ *     background-color: &num;20395a;
+ * }
+ * </programlisting>
+ * </example>
+ * <para>
+ * Widget state pseudoclasses may only apply to the
+ * last element in a selector.
+ * </para>
+ * <para>
+ * All the mentioned elements may be combined to create
+ * complex selectors that match specific widget paths.
+ * As in CSS, rules apply by specificity, so the selectors
+ * describing the best a widget path will take precedence
+ * over the others.
+ * </para>
+ * </refsect2>
+ * <refsect2 id="gtkcssprovider-rules">
+ * <title>&commat; rules</title>
+ * <para>
+ * GTK+'s CSS supports the &commat;import rule, in order
+ * to load another CSS file in addition to the currently
+ * parsed one.
+ * </para>
+ * <example>
+ * <title>Using the &commat;import rule</title>
+ * <programlisting>
+ * &commat;import url (path/to/common.css)
+ * </programlisting>
+ * </example>
+ * <para>
+ * GTK+ also supports an additional &commat;define-color
+ * rule, in order to define a color name which may be used
+ * instead of color numeric representations.
+ * </para>
+ * <example>
+ * <title>Defining colors</title>
+ * <programlisting>
+ * &commat;define-color bg_color &num;f9a039;
+ *
+ * &ast; {
+ *     background-color: &commat;bg_color;
+ * }
+ * </programlisting>
+ * </example>
+ * </refsect2>
+ * <refsect2 id="gtkcssprovider-symbolic-colors">
+ * <title>Symbolic colors</title>
+ * <para>
+ * Besides being able to define color names, the CSS
+ * parser is also able to read different color modifiers,
+ * which can also be nested, providing a rich language
+ * to define colors starting from other colors.
+ * </para>
+ * <example>
+ * <title>Using symbolic colors</title>
+ * <programlisting>
+ * &commat;define-color entry-color shade (&commat;bg_color, 0.7);
+ *
+ * GtkEntry {
+ *     background-color: @entry-color;
+ * }
+ *
+ * GtkEntry:focused {
+ *     background-color: mix (&commat;entry-color,
+ *                            shade (&num;fff, 0.5),
+ *                            0.8);
+ * }
+ * </programlisting>
+ * </example>
+ * </refsect2>
+ * <refsect2 id="gtkcssprovider-properties">
+ * <title>Supported properties</title>
+ * <para>
+ * Properties are the part that differ the most to common CSS,
+ * not all properties are supported (some are planned to be
+ * supported eventually, some others are meaningless or don't
+ * map intuitively in a widget based environment).
+ * </para>
+ * <para>
+ * There is also a difference in shorthand properties, for
+ * example in common CSS it is fine to define a font through
+ * the different @font-family, @font-style, @font-size
+ * properties, meanwhile in GTK+'s CSS only the canonical
+ * @font property would be supported.
+ * </para>
+ * <para>
+ * The currently supported properties are:
+ * </para>
+ * <informaltable>
+ *   <tgroup cols="4">
+ *     <thead>
+ *       <row>
+ *         <entry>Property name</entry>
+ *         <entry>Syntax</entry>
+ *         <entry>Maps to</entry>
+ *         <entry>Examples</entry>
+ *       </row>
+ *     </thead>
+ *     <tbody>
+ *       <row>
+ *         <entry>engine</entry>
+ *         <entry><programlisting>engine-name</programlisting></entry>
+ *         <entry>#GtkThemingEngine</entry>
+ *         <entry><programlisting>engine: clearlooks;</programlisting></entry>
+ *       </row>
+ *       <row>
+ *         <entry>background-color</entry>
+ *         <entry morerows="3"><programlisting>color</programlisting></entry>
+ *         <entry morerows="3">#GdkColor</entry>
+ *         <entry morerows="3">
+ *           <programlisting>
+ * background-color: &num;fff;
+ * foreground-color: @color-name;
+ * text-color: shade (@color-name, 0.5);
+ * base-color: mix (@color-name, &num;f0f, 0.8);</programlisting>
+ *         </entry>
+ *       </row>
+ *       <row>
+ *         <entry>foreground-color</entry>
+ *       </row>
+ *       <row>
+ *         <entry>text-color</entry>
+ *       </row>
+ *       <row>
+ *         <entry>base-color</entry>
+ *       </row>
+ *       <row>
+ *         <entry>font</entry>
+ *         <entry><programlisting>family [style] [size]</programlisting></entry>
+ *         <entry>#PangoFontDescription</entry>
+ *         <entry><programlisting>font: Sans 15;</programlisting></entry>
+ *       </row>
+ *       <row>
+ *         <entry>margin</entry>
+ *         <entry morerows="1">
+ *           <programlisting>
+ * width
+ * vertical-width horizontal-width
+ * top-width horizontal-width bottom-width
+ * top-width right-width bottom-width left-width
+ *           </programlisting>
+ *         </entry>
+ *         <entry morerows="1">#GtkBorder</entry>
+ *         <entry morerows="1">
+ *           <programlisting>
+ * margin: 5;
+ * margin: 5 10;
+ * margin: 5 10 3;
+ * margin: 5 10 3 5;</programlisting>
+ *         </entry>
+ *       </row>
+ *       <row>
+ *         <entry>padding</entry>
+ *       </row>
+ *       <row>
+ *         <entry>background-image</entry>
+ *         <entry>
+ *           <programlisting>
+ * -gtk-gradient (linear,
+ *                starting-x-position starting-y-position,
+ *                ending-x-position ending-y-position,
+ *                [ [from|to] (color) |
+ *                  color-stop (percentage, color) ] )
+ *
+ * -gtk-gradient (radial,
+ *                starting-x-position starting-y-position, starting-radius,
+ *                ending-x-position ending-y-position, ending-radius,
+ *                [ [from|to] (color) |
+ *                  color-stop (percentage, color) ]* )</programlisting>
+ *         </entry>
+ *         <entry>#cairo_pattern_t</entry>
+ *         <entry>
+ *           <programlisting>
+ * -gtk-gradient (linear,
+ *                top left, top right,
+ *                from (&num;fff), to (&num;000));
+ * -gtk-gradient (linear, 0.0 0.5, 0.5 1.0,
+ *                from (&num;fff),
+ *                color-stop (0.5, &num;f00),
+ *                to (&num;000));
+ * -gtk-gradient (radial,
+ *                center center, 0.2,
+ *                center center, 0.8,
+ *                color-stop (0.0, &num;fff),
+ *                color-stop (1.0, &num;000));</programlisting>
+ *         </entry>
+ *       </row>
+ *       <row>
+ *         <entry>border-image</entry>
+ *         <entry><programlisting>url([path]) top-distance right-distance bottom-distance left-distance horizontal-option vertical-option</programlisting></entry>
+ *         <entry></entry>
+ *         <entry>
+ *           <programlisting>
+ * border-image: url (/path/to/image.png) 3 4 3 4 stretch;
+ * border-image: url (/path/to/image.png) 3 4 4 3 repeat stretch;</programlisting>
+ *         </entry>
+ *       </row>
+ *       <row>
+ *         <entry>transition</entry>
+ *         <entry><programlisting>duration [s|ms] [linear|ease|ease-in|ease-out|ease-in-out]</programlisting></entry>
+ *         <entry></entry>
+ *         <entry>
+ *           <programlisting>
+ * transition: 150ms ease-in-out;
+ * transition: 1s linear;</programlisting>
+ *         </entry>
+ *       </row>
+ *     </tbody>
+ *   </tgroup>
+ * </informaltable>
+ * </refsect2>
+ */
+
 typedef struct GtkCssProviderPrivate GtkCssProviderPrivate;
 typedef struct SelectorElement SelectorElement;
 typedef struct SelectorPath SelectorPath;
@@ -753,6 +1107,13 @@ gtk_css_provider_finalize (GObject *object)
   G_OBJECT_CLASS (gtk_css_provider_parent_class)->finalize (object);
 }
 
+/**
+ * gtk_css_provider_new:
+ *
+ * Returns a newly created #GtkCssProvider.
+ *
+ * Returns: A new #GtkCssProvider
+ **/
 GtkCssProvider *
 gtk_css_provider_new (void)
 {
@@ -2235,6 +2596,18 @@ parse_stylesheet (GtkCssProvider *css_provider)
   return TRUE;
 }
 
+/**
+ * gtk_css_provider_load_from_data:
+ * @css_provider: a #GtkCssProvider
+ * @data: CSS data loaded in memory
+ * @length: the length of @data in bytes, or -1 for NUL terminated strings
+ * @error: (out) (allow-none): return location for a #GError, or %NULL
+ *
+ * Loads @data into @css_provider, making it clear any previously loaded
+ * information.
+ *
+ * Returns: %TRUE if the data could be loaded.
+ **/
 gboolean
 gtk_css_provider_load_from_data (GtkCssProvider *css_provider,
                                  const gchar    *data,
@@ -2265,6 +2638,17 @@ gtk_css_provider_load_from_data (GtkCssProvider *css_provider,
   return TRUE;
 }
 
+/**
+ * gtk_css_provider_load_from_file:
+ * @css_provider: a #GtkCssProvider
+ * @file: #GFile pointing to a file to load
+ * @error: (out) (allow-none): return location for a #GError, or %NULL
+ *
+ * Loads the data contained in @file into @css_provider, making it
+ * clear any previously loaded information.
+ *
+ * Returns: %TRUE if the data could be loaded.
+ **/
 gboolean
 gtk_css_provider_load_from_file (GtkCssProvider  *css_provider,
                                  GFile           *file,
@@ -2352,6 +2736,17 @@ gtk_css_provider_load_from_path_internal (GtkCssProvider  *css_provider,
   return TRUE;
 }
 
+/**
+ * gtk_css_provider_load_from_path:
+ * @css_provider: a #GtkCssProvider
+ * @path: the path of a filename to load, in the GLib filename encoding
+ * @error: (out) (allow-none): return location for a #GError, or %NULL
+ *
+ * Loads the data contained in @path into @css_provider, making it clear
+ * any previously loaded information.
+ *
+ * Returns: %TRUE if the data could be loaded.
+ **/
 gboolean
 gtk_css_provider_load_from_path (GtkCssProvider  *css_provider,
                                  const gchar     *path,
@@ -2364,6 +2759,15 @@ gtk_css_provider_load_from_path (GtkCssProvider  *css_provider,
                                                    TRUE, error);
 }
 
+/**
+ * gtk_css_provider_get_default:
+ *
+ * Returns the provider containing the style settings used as a
+ * fallback for all widgets.
+ *
+ * Returns: (transfer none): The provider used for fallback styling.
+ *          This memory is owned by GTK+, and you must not free it.
+ **/
 GtkCssProvider *
 gtk_css_provider_get_default (void)
 {
@@ -2457,6 +2861,16 @@ css_provider_get_theme_dir (void)
   return path;
 }
 
+/**
+ * gtk_css_provider_get_named:
+ * @name: A theme name
+ * @variant: variant to load, for example, "dark", or %NULL for the default
+ *
+ * 
+ *
+ * Returns: (transfer none): The provider used for fallback styling.
+ *          This memory is owned by GTK+, and you must not free it.
+ **/
 GtkCssProvider *
 gtk_css_provider_get_named (const gchar *name,
                             const gchar *variant)
diff --git a/gtk/gtkcssprovider.h b/gtk/gtkcssprovider.h
index 2c6d283..ebfc36d 100644
--- a/gtk/gtkcssprovider.h
+++ b/gtk/gtkcssprovider.h
@@ -31,16 +31,16 @@ G_BEGIN_DECLS
 #define GTK_IS_CSS_PROVIDER_CLASS(c)  (G_TYPE_CHECK_CLASS_TYPE    ((c), GTK_TYPE_CSS_PROVIDER))
 #define GTK_CSS_PROVIDER_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS  ((o), GTK_TYPE_CSS_PROVIDER, GtkCssProviderClass))
 
-typedef struct GtkCssProvider GtkCssProvider;
-typedef struct GtkCssProviderClass GtkCssProviderClass;
+typedef struct _GtkCssProvider GtkCssProvider;
+typedef struct _GtkCssProviderClass GtkCssProviderClass;
 
-struct GtkCssProvider
+struct _GtkCssProvider
 {
   GObject parent_instance;
   gpointer priv;
 };
 
-struct GtkCssProviderClass
+struct _GtkCssProviderClass
 {
   GObjectClass parent_class;
 };
diff --git a/gtk/gtkenums.h b/gtk/gtkenums.h
index 576e641..657ffaa 100644
--- a/gtk/gtkenums.h
+++ b/gtk/gtkenums.h
@@ -544,6 +544,16 @@ typedef enum
   GTK_SIZE_REQUEST_WIDTH_FOR_HEIGHT
 } GtkSizeRequestMode;
 
+/**
+ * GtkStateFlags:
+ * @GTK_STATE_FLAG_ACTIVE: Widget is active.
+ * @GTK_STATE_FLAG_PRELIGHT: Widget has a mouse pointer over it.
+ * @GTK_STATE_FLAG_SELECTED: Widget is selected.
+ * @GTK_STATE_FLAG_INCONSISTENT: Widget is inconsistent.
+ * @GTK_STATE_FLAG_FOCUSED: Widget has the keyboard focus.
+ *
+ * Describes a widget state.
+ */
 typedef enum
 {
   GTK_STATE_FLAG_ACTIVE       = 1 << 0,
@@ -606,6 +616,17 @@ typedef enum
   GTK_WRAP_BOX_V_EXPAND = 1 << 1
 } GtkWrapBoxPacking;
 
+/**
+ * GtkRegionFlags:
+ * @GTK_REGION_EVEN: Region has an even number within a set.
+ * @GTK_REGION_ODD: Region has an odd number within a set.
+ * @GTK_REGION_FIRST: Region is the first one within a set.
+ * @GTK_REGION_LAST: Region is the last one within a set.
+ * @GTK_REGION_DEFAULT: Region is the default option.
+ * @GTK_REGION_SORTED: Region is part of a sorted area.
+ *
+ * Describes a region within a widget.
+ */
 typedef enum {
   GTK_REGION_EVEN    = 1 << 0,
   GTK_REGION_ODD     = 1 << 1,
@@ -615,6 +636,16 @@ typedef enum {
   GTK_REGION_SORTED  = 1 << 5
 } GtkRegionFlags;
 
+/**
+ * GtkJunctionSides:
+ * @GTK_JUNCTION_NONE: No junctions.
+ * @GTK_JUNCTION_TOP: Element connects on the top side.
+ * @GTK_JUNCTION_BOTTOM: Element connects on the bottom side.
+ * @GTK_JUNCTION_LEFT: Element connects on the left side.
+ * @GTK_JUNCTION_RIGHT: Element connects on the right side.
+ *
+ * Describes how a rendered element connects to adjacent elements.
+ */
 typedef enum {
   GTK_JUNCTION_NONE   = 0,
   GTK_JUNCTION_TOP    = 1 << 0,
diff --git a/gtk/gtkstylecontext.c b/gtk/gtkstylecontext.c
index 04a39b5..3a04074 100644
--- a/gtk/gtkstylecontext.c
+++ b/gtk/gtkstylecontext.c
@@ -33,6 +33,163 @@
 #include "gtkanimationdescription.h"
 #include "gtktimeline.h"
 
+/**
+ * SECTION:gtkstylecontext
+ * @Short_description: rendering UI elements
+ * @Title: GtkStyleContext
+ * @See_also:
+ *
+ * #GtkStyleContext is an object that stores styling information affecting
+ * a widget defined by #GtkWidgetPath.
+ *
+ * In order to construct the final style information, #GtkStyleContext
+ * queries information to all attached #GtkStyleProvider<!-- -->s, either
+ * to the context specifically through gtk_style_context_add_provider(), or
+ * to the screen through gtk_style_context_add_provider_for_screen(). The
+ * resulting style is a combination of all provider's information in priority
+ * order.
+ *
+ * For GTK+ widgets, any #GtkStyleContext returned by
+ * gtk_widget_get_style_context() will already have a #GtkWidgetPath, a
+ * #GdkScreen and RTL/LTR information set, the style context will be also
+ * updated automatically if any of these settings change on the widget.
+ *
+ * If you using are the theming layer standalone, you will need to set a
+ * widget path and a screen yourself to the created style context through
+ * gtk_style_context_set_path() and gtk_style_context_set_screen(), as well
+ * as updating the context yourself using gtk_style_context_invalidate()
+ * whenever any of the conditions change, such as a change in the
+ * #GtkSettings:gtk-theme-name property or a hierarchy change in the rendered
+ * widget.
+ *
+ * <refsect2 id="gtkstylecontext-animations">
+ * <title>Transition animations</title>
+ * <para>
+ * #GtkStyleContext has built-in support for state change transitions.
+ * </para>
+ * <note>
+ * For simple widgets where state changes affect the whole widget area,
+ * calling gtk_style_context_notify_state_change() with a %NULL identifier
+ * would be sufficient.
+ * </note>
+ * <para>
+ * If a widget needs to declare several animatable regions (i.e. not
+ * affecting the whole widget area), its #GtkWidget::draw signal handler
+ * needs to wrap the render operations for the different regions around
+ * gtk_style_context_push_animatable_region() and
+ * gtk_style_context_pop_animatable_region(). These functions take an
+ * unique identifier within the style context, for simple widgets with
+ * little animatable regions, an enum may be used:
+ * </para>
+ * <example>
+ * <title>Using an enum as animatable region identifier</title>
+ * <programlisting>
+ * enum {
+ *   REGION_ENTRY,
+ *   REGION_BUTTON_UP,
+ *   REGION_BUTTON_DOWN
+ * };
+ *
+ * ...
+ *
+ * gboolean
+ * spin_button_draw (GtkWidget *widget,
+ *                   cairo_t   *cr)
+ * {
+ *   GtkStyleContext *context;
+ *
+ *   context = gtk_widget_get_style_context (widget);
+ *
+ *   gtk_style_context_push_animatable_region (context,
+ *                                             GUINT_TO_POINTER (REGION_ENTRY));
+ *
+ *   gtk_render_background (cr, 0, 0, 100, 30);
+ *   gtk_render_frame (cr, 0, 0, 100, 30);
+ *
+ *   gtk_style_context_pop_animatable_region (context);
+ *
+ *   ...
+ * }
+ * </programlisting>
+ * </example>
+ * <para>
+ * For complex widgets with an arbitrary number of animatable regions, it
+ * is up to the implementation to come up with a way to univocally identify
+ * an animatable region, pointers to internal structs would suffice.
+ * </para>
+ * <example>
+ * <title>Using an arbitrary pointer as animatable region identifier</title>
+ * <programlisting>
+ * void
+ * notebook_draw_tab (GtkWidget    *widget,
+ *                    NotebookPage *page,
+ *                    cairo_t      *cr)
+ * {
+ *   gtk_style_context_push_animatable_region (context, page);
+ *   gtk_render_extension (cr, page->x, page->y, page->width, page->height);
+ *   gtk_style_context_pop_animatable_region (context);
+ * }
+ * </programlisting>
+ * </example>
+ * <para>
+ * The widget also needs to notify the style context about a state change
+ * for a given animatable region so the animation is triggered.
+ * </para>
+ * <example>
+ * <title>Triggering a state change animation on a region</title>
+ * <programlisting>
+ * gboolean
+ * notebook_motion_notify (GtkWidget      *widget,
+ *                         GdkEventMotion *event)
+ * {
+ *   GtkStyleContext *context;
+ *   NotebookPage *page;
+ *
+ *   context = gtk_widget_get_style_context (widget);
+ *   page = find_page_under_pointer (widget, event);
+ *   gtk_style_context_notify_state_change (context,
+ *                                          gtk_widget_get_window (widget),
+ *                                          page,
+ *                                          GTK_STATE_PRELIGHT,
+ *                                          TRUE);
+ *   ...
+ * }
+ * </programlisting>
+ * </example>
+ * <para>
+ * gtk_style_context_notify_state_change() accepts %NULL region IDs as a
+ * special value, in this case, the whole widget area will be updated
+ * by the animation.
+ * </para>
+ * </refsect2>
+ *
+ * <refsect2 id="gtkstylecontext-custom-styling">
+ * <title>Custom styling in UI libraries and applications</title>
+ * <para>
+ * If you are developing a library with custom #GtkWidget<!-- -->s that
+ * render differently than standard components, you may need to add a
+ * #GtkStyleProvider yourself with the %GTK_STYLE_PROVIDER_PRIORITY_FALLBACK
+ * priority, either a #GtkCssProvider or a custom object implementing the
+ * #GtkStyleProvider interface. This way theming engines may still attempt
+ * to style your UI elements in a different way if needed so.
+ * </para>
+ * <para>
+ * If you are using custom styling on an applications, you probably want then
+ * to make your style information prevail to the theme's, so you must use
+ * a #GtkStyleProvider with the %GTK_STYLE_PROVIDER_PRIORITY_APPLICATION
+ * priority, keep in mind that the user settings in $HOME/.gtk-3.0.css will
+ * still take precedence over your changes, as it uses the
+ * %GTK_STYLE_PROVIDER_PRIORITY_USER priority.
+ * </para>
+ * <para>
+ * If a custom theming engine is needed, you probably want to implement a
+ * #GtkStyleProvider yourself so it points to your #GtkThemingEngine
+ * implementation, as #GtkCssProvider uses gtk_theming_engine_load()
+ * which loads the theming engine module from the standard paths.
+ * </para>
+ * </refsect2>
+ */
+
 typedef struct GtkStyleContextPrivate GtkStyleContextPrivate;
 typedef struct GtkStyleProviderData GtkStyleProviderData;
 typedef struct GtkStyleInfo GtkStyleInfo;
@@ -571,7 +728,7 @@ gtk_style_context_impl_get_property (GObject    *object,
     }
 }
 
-GList *
+static GList *
 find_next_candidate (GList *local,
                      GList *global)
 {
@@ -705,7 +862,7 @@ create_query_path (GtkStyleContext *context)
   return path;
 }
 
-StyleData *
+static StyleData *
 style_data_lookup (GtkStyleContext *context)
 {
   GtkStyleContextPrivate *priv;
@@ -825,6 +982,20 @@ style_provider_remove (GList            **list,
   return FALSE;
 }
 
+/**
+ * gtk_style_context_add_provider:
+ * @context: a #GtkStyleContext
+ * @provider: a #GtkStyleProvider
+ * @priority: the priority of the style provider. The lower
+ *            it is, the earlier it will be used in the style
+ *            construction. Typically this will be in the range
+ *            between %GTK_STYLE_PROVIDER_PRIORITY_FALLBACK and
+ *            %GTK_STYLE_PROVIDER_PRIORITY_USER
+ *
+ * Adds a style provider to @context, to be used in style construction.
+ *
+ * Since: 3.0
+ **/
 void
 gtk_style_context_add_provider (GtkStyleContext  *context,
                                 GtkStyleProvider *provider,
@@ -842,6 +1013,15 @@ gtk_style_context_add_provider (GtkStyleContext  *context,
   gtk_style_context_invalidate (context);
 }
 
+/**
+ * gtk_style_context_remove_provider:
+ * @context: a #GtkStyleContext
+ * @provider: a #GtkStyleProvider
+ *
+ * Removes @provider from the style providers list in @context.
+ *
+ * Since: 3.0
+ **/
 void
 gtk_style_context_remove_provider (GtkStyleContext  *context,
                                    GtkStyleProvider *provider)
@@ -861,6 +1041,19 @@ gtk_style_context_remove_provider (GtkStyleContext  *context,
     }
 }
 
+/**
+ * gtk_style_context_reset_widgets:
+ * @screen: a #GdkScreen
+ *
+ * This function recomputes the styles for all widgets under a particular
+ * #GdkScreen. This is useful when some global parameter has changed that
+ * affects the appearance of all widgets, because when a widget gets a new
+ * style, it will both redraw and recompute any cached information about
+ * its appearance. As an example, it is used when the color scheme changes
+ * in the related #GtkSettings object.
+ *
+ * Since: 3.0
+ **/
 void
 gtk_style_context_reset_widgets (GdkScreen *screen)
 {
@@ -880,6 +1073,22 @@ gtk_style_context_reset_widgets (GdkScreen *screen)
   g_list_free (toplevels);
 }
 
+/**
+ * gtk_style_context_add_provider_for_screen:
+ * @screen: a #GdkScreen
+ * @provider: a #GtkStyleProvider
+ * @priority: the priority of the style provider. The lower
+ *            it is, the earlier it will be used in the style
+ *            construction. Typically this will be in the range
+ *            between %GTK_STYLE_PROVIDER_PRIORITY_FALLBACK and
+ *            %GTK_STYLE_PROVIDER_PRIORITY_USER
+ *
+ * Adds a global style provider to @screen, which will be used
+ * in style construction for all #GtkStyleContext<!-- -->s under
+ * @screen.
+ *
+ * Since: 3.0
+ **/
 void
 gtk_style_context_add_provider_for_screen (GdkScreen        *screen,
                                            GtkStyleProvider *provider,
@@ -902,6 +1111,15 @@ gtk_style_context_add_provider_for_screen (GdkScreen        *screen,
   gtk_style_context_reset_widgets (screen);
 }
 
+/**
+ * gtk_style_context_remove_provider_for_screen:
+ * @screen: a #GdkScreen
+ * @provider: a #GtkStyleProvider
+ *
+ * Removes @provider from the global style providers list in @screen.
+ *
+ * Since: 3.0
+ **/
 void
 gtk_style_context_remove_provider_for_screen (GdkScreen        *screen,
                                               GtkStyleProvider *provider)
@@ -925,6 +1143,18 @@ gtk_style_context_remove_provider_for_screen (GdkScreen        *screen,
     }
 }
 
+/**
+ * gtk_style_context_get_property:
+ * @context: a #GtkStyleContext
+ * @property: style property name
+ * @state: state to retrieve the property value for
+ * @value: (out) (transfer full):  return location for the style property value.
+ *
+ * Gets a style property from @context for the given state. When done with @value,
+ * g_value_unset() needs to be called to free any allocated memory.
+ *
+ * Since: 3.0
+ **/
 void
 gtk_style_context_get_property (GtkStyleContext *context,
                                 const gchar     *property,
@@ -946,6 +1176,16 @@ gtk_style_context_get_property (GtkStyleContext *context,
   gtk_style_set_get_property (data->store, property, state, value);
 }
 
+/**
+ * gtk_style_context_get_valist:
+ * @context: a #GtkStyleContext
+ * @state: state to retrieve the property values for
+ * @args: va_list of property name/return location pairs, followed by %NULL
+ *
+ * Retrieves several style property values from @context for a given state.
+ *
+ * Since: 3.0
+ **/
 void
 gtk_style_context_get_valist (GtkStyleContext *context,
                               GtkStateFlags    state,
@@ -963,6 +1203,17 @@ gtk_style_context_get_valist (GtkStyleContext *context,
   gtk_style_set_get_valist (data->store, state, args);
 }
 
+/**
+ * gtk_style_context_get:
+ * @context: a #GtkStyleContext
+ * @state: state to retrieve the property values for
+ * @...: property name /return value pairs, followed by %NULL
+ *
+ * Retrieves several style property values from @context for a
+ * given state.
+ *
+ * Since: 3.0
+ **/
 void
 gtk_style_context_get (GtkStyleContext *context,
                        GtkStateFlags    state,
@@ -984,6 +1235,16 @@ gtk_style_context_get (GtkStyleContext *context,
   va_end (args);
 }
 
+/**
+ * gtk_style_context_set_state:
+ * @context: a #GtkStyleContext
+ * @flags: state to represent
+ *
+ * Sets the style to be used when rendering with any
+ * of the "gtk_render_" prefixed functions.
+ *
+ * Since: 3.0
+ **/
 void
 gtk_style_context_set_state (GtkStyleContext *context,
                              GtkStateFlags    flags)
@@ -996,6 +1257,16 @@ gtk_style_context_set_state (GtkStyleContext *context,
   priv->state_flags = flags;
 }
 
+/**
+ * gtk_style_context_get_state:
+ * @context: a #GtkStyleContext
+ *
+ * returns the state used when rendering.
+ *
+ * Returns: the state flags
+ *
+ * Since: 3.0
+ **/
 GtkStateFlags
 gtk_style_context_get_state (GtkStyleContext *context)
 {
@@ -1093,6 +1364,19 @@ gtk_style_context_is_state_set (GtkStyleContext *context,
   return state_set;
 }
 
+/**
+ * gtk_style_context_set_path:
+ * @context: a #GtkStyleContext
+ * @path: a #GtkWidgetPath
+ *
+ * Sets the #GtkWidgetPath used for style matching. As a
+ * consequence, the style will be regenerated to match
+ * the new given path. If you are using a #GtkStyleContext
+ * returned from gtk_widget_get_style_context(), you do
+ * not need to call this yourself.
+ *
+ * Since: 3.0
+ **/
 void
 gtk_style_context_set_path (GtkStyleContext *context,
                             GtkWidgetPath   *path)
@@ -1116,6 +1400,16 @@ gtk_style_context_set_path (GtkStyleContext *context,
   gtk_style_context_invalidate (context);
 }
 
+/**
+ * gtk_style_context_get_path:
+ * @context: a #GtkStyleContext
+ *
+ * Returns the widget path used for style matching.
+ *
+ * Returns: (transfer none): A #GtkWidgetPath
+ *
+ * Since: 3.0
+ **/
 G_CONST_RETURN GtkWidgetPath *
 gtk_style_context_get_path (GtkStyleContext *context)
 {
@@ -1125,6 +1419,18 @@ gtk_style_context_get_path (GtkStyleContext *context)
   return priv->widget_path;
 }
 
+/**
+ * gtk_style_context_save:
+ * @context: a #GtkStyleContext
+ *
+ * Saves the @context state, so all modifications done through
+ * gtk_style_context_set_class(), gtk_style_context_unset_class(),
+ * gtk_style_context_set_region(), gtk_style_context_unset_region()
+ * or gtk_style_context_set_junction_sides() can be reverted in one
+ * go through gtk_style_context_restore().
+ *
+ * Since: 3.0
+ **/
 void
 gtk_style_context_save (GtkStyleContext *context)
 {
@@ -1141,6 +1447,15 @@ gtk_style_context_save (GtkStyleContext *context)
   priv->info_stack = g_slist_prepend (priv->info_stack, info);
 }
 
+/**
+ * gtk_style_context_restore:
+ * @context: a #GtkStyleContext
+ *
+ * Restores @context state to a previous stage. See
+ * gtk_style_context_save().
+ *
+ * Since: 3.0
+ **/
 void
 gtk_style_context_restore (GtkStyleContext *context)
 {
@@ -1262,6 +1577,30 @@ region_find (GArray *array,
   return found;
 }
 
+/**
+ * gtk_style_context_set_class:
+ * @context: a #GtkStyleContext
+ * @class_name: class name to use in styling
+ *
+ * Sets a class name to @context, so posterior calls to
+ * gtk_style_context_get() or any of the gtk_render_*
+ * functions will make use of this new class for styling.
+ *
+ * In the CSS file format, a #GtkEntry defining an "entry"
+ * class, would be matched by:
+ *
+ * <programlisting>
+ * GtkEntry.entry { ... }
+ * </programlisting>
+ *
+ * While any widget defining an "entry" class would be
+ * matched by:
+ * <programlisting>
+ * .entry { ... }
+ * </programlisting>
+ *
+ * Since: 3.0
+ **/
 void
 gtk_style_context_set_class (GtkStyleContext *context,
                              const gchar     *class_name)
@@ -1289,6 +1628,15 @@ gtk_style_context_set_class (GtkStyleContext *context,
     }
 }
 
+/**
+ * gtk_style_context_unset_class:
+ * @context: a #GtkStyleContext
+ * @class_name: class name to remove
+ *
+ * Removes @class_name from @context.
+ *
+ * Since: 3.0
+ **/
 void
 gtk_style_context_unset_class (GtkStyleContext *context,
                                const gchar     *class_name)
@@ -1320,6 +1668,18 @@ gtk_style_context_unset_class (GtkStyleContext *context,
     }
 }
 
+/**
+ * gtk_style_context_has_class:
+ * @context: a #GtkStyleContext
+ * @class_name: a class name
+ *
+ * Returns %TRUE if @context currently has defined the
+ * given class name
+ *
+ * Returns: %TRUE if @context has @class_name defined
+ *
+ * Since: 3.0
+ **/
 gboolean
 gtk_style_context_has_class (GtkStyleContext *context,
                              const gchar     *class_name)
@@ -1347,6 +1707,19 @@ gtk_style_context_has_class (GtkStyleContext *context,
   return FALSE;
 }
 
+/**
+ * gtk_style_context_list_classes:
+ * @context: a #GtkStyleContext
+ *
+ * Returns the list of classes currently defined in @context.
+ *
+ * Returns: (transfer container) (element-type utf8): a #GList of
+ *          strings with the currently defined classes. The contents
+ *          of the list are owned by GTK+, but you must free the list
+ *          itself with g_list_free() when you are done with it.
+ *
+ * Since: 3.0
+ **/
 GList *
 gtk_style_context_list_classes (GtkStyleContext *context)
 {
@@ -1373,6 +1746,20 @@ gtk_style_context_list_classes (GtkStyleContext *context)
   return classes;
 }
 
+/**
+ * gtk_style_context_list_regions:
+ * @context: a #GtkStyleContext
+ *
+ *
+ * Returns the list of regions currently defined in @context.
+ *
+ * Returns: (transfer container) (element-type utf8): a #GList of
+ *          strings with the currently defined regions. The contents
+ *          of the list are owned by GTK+, but you must free the list
+ *          itself with g_list_free() when you are done with it.
+ *
+ * Since: 3.0
+ **/
 GList *
 gtk_style_context_list_regions (GtkStyleContext *context)
 {
@@ -1402,30 +1789,58 @@ gtk_style_context_list_regions (GtkStyleContext *context)
   return classes;
 }
 
+/**
+ * gtk_style_context_set_region:
+ * @context: a #GtkStyleContext
+ * @region_name: region name to use in styling
+ * @flags: flags that apply to the region
+ *
+ * Sets a region to @context, so posterior calls to
+ * gtk_style_context_get() or any of the gtk_render_*
+ * functions will make use of this new region for styling.
+ *
+ * In the CSS file format, a #GtkTreeView defining a "row"
+ * region, would be matched by:
+ *
+ * <programlisting>
+ * GtkTreeView row { ... }
+ * </programlisting>
+ *
+ * pseudo-classes are used for matching @flags, so the two
+ * following rules:
+ * <programlisting>
+ * GtkTreeView row:nth-child (even) { ... }
+ * GtkTreeView row:nth-child (odd) { ... }
+ * </programlisting>
+ *
+ * would apply to even and odd rows, respectively.
+ *
+ * Since: 3.0
+ **/
 void
 gtk_style_context_set_region (GtkStyleContext *context,
-                              const gchar     *class_name,
+                              const gchar     *region_name,
                               GtkRegionFlags   flags)
 {
   GtkStyleContextPrivate *priv;
   GtkStyleInfo *info;
-  GQuark class_quark;
+  GQuark region_quark;
   guint position;
 
   g_return_if_fail (GTK_IS_STYLE_CONTEXT (context));
-  g_return_if_fail (class_name != NULL);
+  g_return_if_fail (region_name != NULL);
 
   priv = context->priv;
-  class_quark = g_quark_from_string (class_name);
+  region_quark = g_quark_from_string (region_name);
 
   g_assert (priv->info_stack != NULL);
   info = priv->info_stack->data;
 
-  if (!region_find (info->regions, class_quark, &position))
+  if (!region_find (info->regions, region_quark, &position))
     {
       GtkRegion region;
 
-      region.class_quark = class_quark;
+      region.class_quark = region_quark;
       region.flags = flags;
 
       g_array_insert_val (info->regions, position, region);
@@ -1435,21 +1850,30 @@ gtk_style_context_set_region (GtkStyleContext *context,
     }
 }
 
+/**
+ * gtk_style_context_unset_region:
+ * @context: a #GtkStyleContext
+ * @region_name: region name to unset
+ *
+ * Removes a region from @context
+ *
+ * Since: 3.0
+ **/
 void
-gtk_style_context_unset_region (GtkStyleContext    *context,
-                                const gchar        *class_name)
+gtk_style_context_unset_region (GtkStyleContext *context,
+                                const gchar     *region_name)
 {
   GtkStyleContextPrivate *priv;
   GtkStyleInfo *info;
-  GQuark class_quark;
+  GQuark region_quark;
   guint position;
 
   g_return_if_fail (GTK_IS_STYLE_CONTEXT (context));
-  g_return_if_fail (class_name != NULL);
+  g_return_if_fail (region_name != NULL);
 
-  class_quark = g_quark_try_string (class_name);
+  region_quark = g_quark_try_string (region_name);
 
-  if (!class_quark)
+  if (!region_quark)
     return;
 
   priv = context->priv;
@@ -1457,7 +1881,7 @@ gtk_style_context_unset_region (GtkStyleContext    *context,
   g_assert (priv->info_stack != NULL);
   info = priv->info_stack->data;
 
-  if (region_find (info->regions, class_quark, &position))
+  if (region_find (info->regions, region_quark, &position))
     {
       g_array_remove_index (info->regions, position);
 
@@ -1466,25 +1890,38 @@ gtk_style_context_unset_region (GtkStyleContext    *context,
     }
 }
 
+/**
+ * gtk_style_context_has_region:
+ * @context: a #GtkStyleContext
+ * @region_name: a region name
+ * @flags_return: (out) (allow-none): return location for region flags
+ *
+ * Returns %TRUE if @context has the region defined. If @flags_return is
+ * not %NULL, it is set to the flags affecting the region.
+ *
+ * Returns: %TRUE if region is defined
+ *
+ * Since: 3.0
+ **/
 gboolean
 gtk_style_context_has_region (GtkStyleContext *context,
-                              const gchar     *class_name,
+                              const gchar     *region_name,
                               GtkRegionFlags  *flags_return)
 {
   GtkStyleContextPrivate *priv;
   GtkStyleInfo *info;
-  GQuark class_quark;
+  GQuark region_quark;
   guint position;
 
   g_return_val_if_fail (GTK_IS_STYLE_CONTEXT (context), FALSE);
-  g_return_val_if_fail (class_name != NULL, FALSE);
+  g_return_val_if_fail (region_name != NULL, FALSE);
 
   if (flags_return)
     *flags_return = 0;
 
-  class_quark = g_quark_try_string (class_name);
+  region_quark = g_quark_try_string (region_name);
 
-  if (!class_quark)
+  if (!region_quark)
     return FALSE;
 
   priv = context->priv;
@@ -1492,7 +1929,7 @@ gtk_style_context_has_region (GtkStyleContext *context,
   g_assert (priv->info_stack != NULL);
   info = priv->info_stack->data;
 
-  if (region_find (info->regions, class_quark, &position))
+  if (region_find (info->regions, region_quark, &position))
     {
       if (flags_return)
         {
@@ -1581,6 +2018,15 @@ _gtk_style_context_peek_style_property (GtkStyleContext *context,
   return &pcache->value;
 }
 
+/**
+ * gtk_style_context_get_style_property:
+ * @context: a #GtkStyleContext
+ * @property_name: the name of the widget style property
+ * @value: (out) (transfer full): Return location for the property value, free with
+ *         g_value_unset() after use.
+ *
+ * Gets the value for a widget style property.
+ **/
 void
 gtk_style_context_get_style_property (GtkStyleContext *context,
                                       const gchar     *property_name,
@@ -1631,6 +2077,16 @@ gtk_style_context_get_style_property (GtkStyleContext *context,
                G_VALUE_TYPE_NAME (value));
 }
 
+/**
+ * gtk_style_context_get_style_valist:
+ * @context: a #GtkStyleContext
+ * @args: va_list of property name/return location pairs, followed by %NULL
+ *
+ * Retrieves several widget style properties from @context according to the
+ * current style.
+ *
+ * Since: 3.0
+ **/
 void
 gtk_style_context_get_style_valist (GtkStyleContext *context,
                                     va_list          args)
@@ -1688,6 +2144,16 @@ gtk_style_context_get_style_valist (GtkStyleContext *context,
     }
 }
 
+/**
+ * gtk_style_context_get_style:
+ * @context: a #GtkStyleContext
+ * @...: property name /return value pairs, followed by %NULL
+ *
+ * Retrieves several widget style properties from @context according to the
+ * current style.
+ *
+ * Since: 3.0
+ **/
 void
 gtk_style_context_get_style (GtkStyleContext *context,
                              ...)
@@ -1702,6 +2168,17 @@ gtk_style_context_get_style (GtkStyleContext *context,
 }
 
 
+/**
+ * gtk_style_context_lookup_icon_set:
+ * @context: a #GtkStyleContext
+ * @stock_id: an icon name
+ *
+ * Looks up @stock_id in the icon factories associated to @context and
+ * the default icon factory, returning an icon set if found, otherwise
+ * %NULL.
+ *
+ * Returns: (transfer none): The looked  up %GtkIconSet, or %NULL
+ **/
 GtkIconSet *
 gtk_style_context_lookup_icon_set (GtkStyleContext *context,
 				   const gchar     *stock_id)
@@ -1733,6 +2210,18 @@ gtk_style_context_lookup_icon_set (GtkStyleContext *context,
   return gtk_icon_factory_lookup_default (stock_id);
 }
 
+/**
+ * gtk_style_context_set_screen:
+ * @context: a #GtkStyleContext
+ * @screen: a #GdkScreen
+ *
+ * Sets the screen to which @context will be attached to, @screen
+ * is used in order to reconstruct style based on the global providers
+ * list. If you are using a #GtkStyleContext returned from
+ * gtk_widget_get_style_context(), you do not need to call this yourself.
+ *
+ * Since: 3.0
+ **/
 void
 gtk_style_context_set_screen (GtkStyleContext *context,
                               GdkScreen       *screen)
@@ -1749,6 +2238,14 @@ gtk_style_context_set_screen (GtkStyleContext *context,
   gtk_style_context_invalidate (context);
 }
 
+/**
+ * gtk_style_context_get_screen:
+ * @context: a #GtkStyleContext
+ *
+ * Returns the #GdkScreen to which @context is attached to.
+ *
+ * Returns: a #GdkScreen, or %NULL.
+ **/
 GdkScreen *
 gtk_style_context_get_screen (GtkStyleContext *context)
 {
@@ -1760,6 +2257,17 @@ gtk_style_context_get_screen (GtkStyleContext *context)
   return priv->screen;
 }
 
+/**
+ * gtk_style_context_set_direction:
+ * @context: a #GtkStyleContext
+ * @direction: the new direction.
+ *
+ * Sets the reading direction for rendering purposes. If you are
+ * using a #GtkStyleContext returned from gtk_widget_get_style_context(),
+ * you do not need to call this yourself.
+ *
+ * Since: 3.0
+ **/
 void
 gtk_style_context_set_direction (GtkStyleContext  *context,
                                  GtkTextDirection  direction)
@@ -1774,6 +2282,16 @@ gtk_style_context_set_direction (GtkStyleContext  *context,
   g_object_notify (G_OBJECT (context), "direction");
 }
 
+/**
+ * gtk_style_context_get_direction:
+ * @context: a #GtkStyleContext
+ *
+ * Returns the widget direction used for rendering.
+ *
+ * Returns: the widget direction
+ *
+ * Since: 3.0
+ **/
 GtkTextDirection
 gtk_style_context_get_direction (GtkStyleContext *context)
 {
@@ -1785,6 +2303,17 @@ gtk_style_context_get_direction (GtkStyleContext *context)
   return priv->direction;
 }
 
+/**
+ * gtk_style_context_set_junction_sides:
+ * @context: a #GtkStyleContext
+ * @sides: sides where rendered elements are visually connected to other elements.
+ *
+ * Sets the sides where rendered elements (mostly through gtk_render_frame()) will
+ * visually connect with other visual elements. This is merely a guideline that may
+ * be honored or not in theming engines.
+ *
+ * Since: 3.0
+ **/
 void
 gtk_style_context_set_junction_sides (GtkStyleContext  *context,
 				      GtkJunctionSides  sides)
@@ -1799,6 +2328,16 @@ gtk_style_context_set_junction_sides (GtkStyleContext  *context,
   info->junction_sides = sides;
 }
 
+/**
+ * gtk_style_context_get_junction_sides:
+ * @context: a #GtkStyleContext
+ *
+ * Returns the sides where rendered elements connect visually with others.
+ *
+ * Returns: the junction sides
+ *
+ * Since: 3.0
+ **/
 GtkJunctionSides
 gtk_style_context_get_junction_sides (GtkStyleContext *context)
 {
@@ -1812,6 +2351,16 @@ gtk_style_context_get_junction_sides (GtkStyleContext *context)
   return info->junction_sides;
 }
 
+/**
+ * gtk_style_context_lookup_color:
+ * @context: a #GtkStyleContext
+ * @color_name: color name to lookup
+ * @color: (out): Return location for the looked up color
+ *
+ * Looks up and resolves a color name in the @context color map.
+ *
+ * Returns: %TRUE if @color_name was found and resolved, %FALSE otherwise
+ **/
 gboolean
 gtk_style_context_lookup_color (GtkStyleContext *context,
                                 const gchar     *color_name,
@@ -1837,6 +2386,53 @@ gtk_style_context_lookup_color (GtkStyleContext *context,
   return gtk_symbolic_color_resolve (sym_color, data->store, color);
 }
 
+/**
+ * gtk_style_context_notify_state_change:
+ * @context: a #GtkStyleContext
+ * @window: a #GdkWindow
+ * @region_id: (allow-none): animatable region to notify on, or %NULL.
+ *             See gtk_style_context_push_animatable_region()
+ * @state: state to trigger transition for
+ * @state_value: target value of @state
+ *
+ * Notifies a state change on @context, so if the current style makes use
+ * of transition animations, one will be started so all rendered elements
+ * under @region_id are animated for state @state being set to value @state_value.
+ *
+ * The @window parameter is used in order to invalidate the rendered area
+ * as the animation runs, so make sure it is the same window that is being
+ * rendered on by the gtk_render_*() methods.
+ *
+ * If @region_id is %NULL, all rendered elements using @context will be
+ * affected by this state transition.
+ *
+ * As a practical example, a #GtkButton notifying a state transition on
+ * the prelight state:
+ * <programlisting>
+ * gtk_style_context_notify_state_change (context,
+ *                                        gtk_widget_get_window (widget),
+ *                                        NULL, GTK_STATE_PRELIGHT,
+ *                                        button->in_button);
+ * </programlisting>
+ *
+ * Could be handled in the CSS file like this:
+ * <programlisting>
+ * GtkButton {
+ *     background-color: #f00;
+ * }
+ *
+ * GtkButton:hover {
+ *     background-color: #fff;
+ *     transition: 200ms linear;
+ * }
+ * </programlisting>
+ *
+ * This combination would animate the button background from red to white
+ * if a pointer enters the button, and back to red if the pointer leaves
+ * the button.
+ *
+ * Since: 3.0
+ **/
 void
 gtk_style_context_notify_state_change (GtkStyleContext *context,
                                        GdkWindow       *window,
@@ -1931,6 +2527,22 @@ gtk_style_context_notify_state_change (GtkStyleContext *context,
   gtk_animation_description_unref (desc);
 }
 
+/**
+ * gtk_style_context_push_animatable_region:
+ * @context: a #GtkStyleContext
+ * @region_id: unique identifier for the animatable region
+ *
+ * Pushes an animatable region, so all further gtk_render_*() calls between
+ * this call and the following gtk_style_context_pop_animatable_region() will
+ * potentially show transition animations for if gtk_style_context_notify_state_change()
+ * is called for a given state, and the theme/style used contemplates the use of
+ * transition animations for state changes.
+ *
+ * The @region_id used must be unique in @context so the theming engine may
+ * univocally identify rendered elements subject to a state transition.
+ *
+ * Since: 3.0
+ **/
 void
 gtk_style_context_push_animatable_region (GtkStyleContext *context,
                                           gpointer         region_id)
@@ -1944,6 +2556,14 @@ gtk_style_context_push_animatable_region (GtkStyleContext *context,
   priv->animation_regions = g_slist_prepend (priv->animation_regions, region_id);
 }
 
+/**
+ * gtk_style_context_pop_animatable_region:
+ * @context: a #GtkStyleContext
+ *
+ * Pops an animatable region from @context. See gtk_style_context_push_animatable_region().
+ *
+ * Since: 3.0
+ **/
 void
 gtk_style_context_pop_animatable_region (GtkStyleContext *context)
 {
@@ -2074,6 +2694,16 @@ store_animation_region (GtkStyleContext *context,
     }
 }
 
+/**
+ * gtk_style_context_invalidate:
+ * @context: a #GtkStyleContext.
+ *
+ * Invalidates @context style information, so it will be reconstructed
+ * again. If you're using a #GtkStyleContext returned from
+ * gtk_widget_get_style_context(), you do not need to call this yourself.
+ *
+ * Since: 3.0
+ **/
 void
 gtk_style_context_invalidate (GtkStyleContext *context)
 {
diff --git a/gtk/gtkstylecontext.h b/gtk/gtkstylecontext.h
index 9bab375..a9843f3 100644
--- a/gtk/gtkstylecontext.h
+++ b/gtk/gtkstylecontext.h
@@ -33,16 +33,16 @@ G_BEGIN_DECLS
 #define GTK_IS_STYLE_CONTEXT_CLASS(c)  (G_TYPE_CHECK_CLASS_TYPE    ((c), GTK_TYPE_STYLE_CONTEXT))
 #define GTK_STYLE_CONTEXT_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS  ((o), GTK_TYPE_STYLE_CONTEXT, GtkStyleContextClass))
 
-typedef struct GtkStyleContext GtkStyleContext;
-typedef struct GtkStyleContextClass GtkStyleContextClass;
+typedef struct _GtkStyleContext GtkStyleContext;
+typedef struct _GtkStyleContextClass GtkStyleContextClass;
 
-struct GtkStyleContext
+struct _GtkStyleContext
 {
   GObject parent_object;
   gpointer priv;
 };
 
-struct GtkStyleContextClass
+struct _GtkStyleContextClass
 {
   GObjectClass parent_class;
 
diff --git a/gtk/gtkstyleprovider.c b/gtk/gtkstyleprovider.c
index 2c23a80..2a9d2fc 100644
--- a/gtk/gtkstyleprovider.c
+++ b/gtk/gtkstyleprovider.c
@@ -23,6 +23,16 @@
 #include "gtkstyleprovider.h"
 #include "gtkintl.h"
 
+/**
+ * SECTION:gtkstyleprovider
+ * @Short_description: Interface to provide style information to #GtkStyleContext
+ * @Title: GtkStyleProvider
+ * @See_also: #GtkStyleContext, #GtkCssProvider
+ *
+ * #GtkStyleProvider is an interface used to provide style information to a #GtkStyleContext,
+ * see gtk_style_context_add_provider() and gtk_style_context_add_provider_for_screen().
+ */
+
 static void gtk_style_provider_iface_init (gpointer g_iface);
 
 GType
@@ -44,6 +54,18 @@ gtk_style_provider_iface_init (gpointer g_iface)
 {
 }
 
+/**
+ * gtk_style_provider_get_style:
+ * @provider: a #GtkStyleProvider
+ * @path: #GtkWidgetPath to query
+ *
+ * Returns the style settings affecting a widget defined by @path, or %NULL if
+ * @provider doesn't contemplate styling @path.
+ *
+ * Returns: a #GtkStyleSet containing the style settings affecting @path
+ *
+ * Since: 3.0
+ **/
 GtkStyleSet *
 gtk_style_provider_get_style (GtkStyleProvider *provider,
                               GtkWidgetPath    *path)
@@ -60,16 +82,28 @@ gtk_style_provider_get_style (GtkStyleProvider *provider,
   return iface->get_style (provider, path);
 }
 
+/**
+ * gtk_style_provider_get_style_property:
+ * @provider: a #GtkStyleProvider
+ * @path: #GtkWidgetPath to query
+ * @property_name: the property name
+ * @value: (out): return location for the property value
+ *
+ * Looks up a widget style property as defined by @provider for
+ * the widget represented by @widget_path.
+ *
+ * Returns: %TRUE if the property was found and has a value, %FALSE otherwise
+ **/
 gboolean
 gtk_style_provider_get_style_property (GtkStyleProvider *provider,
-                                       GtkWidgetPath    *widget_path,
+                                       GtkWidgetPath    *path,
                                        const gchar      *property_name,
                                        GValue           *value)
 {
   GtkStyleProviderIface *iface;
 
   g_return_val_if_fail (GTK_IS_STYLE_PROVIDER (provider), FALSE);
-  g_return_val_if_fail (widget_path != NULL, FALSE);
+  g_return_val_if_fail (path != NULL, FALSE);
   g_return_val_if_fail (property_name != NULL, FALSE);
   g_return_val_if_fail (value != NULL, FALSE);
 
@@ -78,9 +112,21 @@ gtk_style_provider_get_style_property (GtkStyleProvider *provider,
   if (!iface->get_style_property)
     return FALSE;
 
-  return iface->get_style_property (provider, widget_path, property_name, value);
+  return iface->get_style_property (provider, path, property_name, value);
 }
 
+/**
+ * gtk_style_provider_get_icon_factory:
+ * @provider: a #GtkStyleProvider
+ * @path: #GtkWidgetPath to query
+ *
+ * Returns the #GtkIconFactory defined to be in use for @path, or %NULL if none
+ * is defined.
+ *
+ * Returns: The icon factory to use for @path, or %NULL
+ *
+ * Since: 3.0
+ **/
 GtkIconFactory *
 gtk_style_provider_get_icon_factory (GtkStyleProvider *provider,
 				     GtkWidgetPath    *path)
diff --git a/gtk/gtkstyleprovider.h b/gtk/gtkstyleprovider.h
index 556b257..0f763a2 100644
--- a/gtk/gtkstyleprovider.h
+++ b/gtk/gtkstyleprovider.h
@@ -39,10 +39,16 @@ G_BEGIN_DECLS
 #define GTK_STYLE_PROVIDER_PRIORITY_APPLICATION 600
 #define GTK_STYLE_PROVIDER_PRIORITY_USER        800
 
-typedef struct GtkStyleProviderIface GtkStyleProviderIface;
-typedef struct GtkStyleProvider GtkStyleProvider; /* dummy typedef */
-
-struct GtkStyleProviderIface
+typedef struct _GtkStyleProviderIface GtkStyleProviderIface;
+typedef struct _GtkStyleProvider GtkStyleProvider; /* dummy typedef */
+
+/**
+ * GtkStyleProviderIface
+ * @get_style: Gets a set of style information that applies to a widget path.
+ * @get_style_property: Gets the value of a widget style property that applies to a widget path.
+ * @get_icon_factory: Gets the icon factory that applies to a widget path.
+ */
+struct _GtkStyleProviderIface
 {
   GTypeInterface g_iface;
 
diff --git a/gtk/gtkstyleset.c b/gtk/gtkstyleset.c
index 2f71f71..2464162 100644
--- a/gtk/gtkstyleset.c
+++ b/gtk/gtkstyleset.c
@@ -325,6 +325,21 @@ property_node_lookup (GQuark quark)
 }
 
 /* Property registration functions */
+
+/**
+ * gtk_style_set_register_property:
+ * @property_name: property name to register
+ * @type: #GType the property will hold
+ * @default_value: default value for this property
+ * @parse_func: parsing function to use, or %NULL
+ *
+ * Registers a property so it can be used in the CSS file format.
+ * This function is the low-level equivalent of
+ * gtk_theming_engine_register_property(), if you are implementing
+ * a theming engine, you want to use that function instead.
+ *
+ * Since: 3.0
+ **/
 void
 gtk_style_set_register_property (const gchar            *property_name,
                                  GType                   type,
@@ -377,6 +392,20 @@ gtk_style_set_register_property (const gchar            *property_name,
   g_array_insert_val (properties, i, new);
 }
 
+/**
+ * gtk_style_set_lookup_property:
+ * @property_name: property name to look up
+ * @type: (out): return location for the looked up property type
+ * @parse_func: (out): return value for the parse function
+ *
+ * Returns %TRUE if a property has been registered, if @type or
+ * @parse_func are not %NULL, the property #GType and parsing function
+ * will be respectively returned.
+ *
+ * Returns: %TRUE if the property is registered, %FALSE otherwise
+ *
+ * Since: 3.0
+ **/
 gboolean
 gtk_style_set_lookup_property (const gchar            *property_name,
                                GType                  *type,
@@ -425,12 +454,30 @@ gtk_style_set_lookup_property (const gchar            *property_name,
 
 /* GtkStyleSet methods */
 
+/**
+ * gtk_style_set_new:
+ *
+ * Returns a newly created #GtkStyleSet
+ *
+ * Returns: a new #GtkStyleSet
+ **/
 GtkStyleSet *
 gtk_style_set_new (void)
 {
   return g_object_new (GTK_TYPE_STYLE_SET, NULL);
 }
 
+/**
+ * gtk_style_set_map_color:
+ * @set: a #GtkStyleSet
+ * @name: color name
+ * @color: #GtkSymbolicColor to map @name to
+ *
+ * Maps @color so it can be referenced by @name. See
+ * gtk_style_set_lookup_color()
+ *
+ * Since: 3.0
+ **/
 void
 gtk_style_set_map_color (GtkStyleSet      *set,
 			 const gchar      *name,
@@ -455,6 +502,18 @@ gtk_style_set_map_color (GtkStyleSet      *set,
                         gtk_symbolic_color_ref (color));
 }
 
+/**
+ * gtk_style_set_lookup_color:
+ * @set: a #GtkStyleSet
+ * @name: color name to lookup
+ *
+ * Returns the symbolic color that is mapped
+ * to @name.
+ *
+ * Returns: The mapped color
+ *
+ * Since: 3.0
+ **/
 GtkSymbolicColor *
 gtk_style_set_lookup_color (GtkStyleSet *set,
 			    const gchar *name)
@@ -472,6 +531,17 @@ gtk_style_set_lookup_color (GtkStyleSet *set,
   return g_hash_table_lookup (priv->color_map, name);
 }
 
+/**
+ * gtk_style_set_set_property:
+ * @set: a #GtkStyleSet
+ * @property: styling property to set
+ * @state: state to set the value for
+ * @value: new value for the property
+ *
+ * Sets a styling property in @set.
+ *
+ * Since: 3.0
+ **/
 void
 gtk_style_set_set_property (GtkStyleSet   *set,
                             const gchar   *property,
@@ -538,6 +608,16 @@ gtk_style_set_set_property (GtkStyleSet   *set,
   g_value_copy (value, val);
 }
 
+/**
+ * gtk_style_set_set_valist:
+ * @set: a #GtkStyleSet
+ * @state: state to set the values for
+ * @args: va_list of property name/value pairs, followed by %NULL
+ *
+ * Sets several style properties on @set.
+ *
+ * Since: 3.0
+ **/
 void
 gtk_style_set_set_valist (GtkStyleSet   *set,
                           GtkStateFlags  state,
@@ -597,6 +677,16 @@ gtk_style_set_set_valist (GtkStyleSet   *set,
     }
 }
 
+/**
+ * gtk_style_set_set:
+ * @set: a #GtkStyleSet
+ * @state: state to set the values for
+ * @...: property name/value pairs, followed by %NULL
+ *
+ * Sets several style properties on @set.
+ *
+ * Since: 3.0
+ **/
 void
 gtk_style_set_set (GtkStyleSet   *set,
                    GtkStateFlags  state,
@@ -646,6 +736,20 @@ resolve_gradient (GtkStyleSet *set,
   return TRUE;
 }
 
+/**
+ * gtk_style_set_get_property:
+ * @set: a #GtkStyleSet
+ * @property: style property name
+ * @state: state to retrieve the property value for
+ * @value: (out) (transfer full):  return location for the style property value.
+ *
+ * Gets a style property from @set for the given state. When done with @value,
+ * g_value_unset() needs to be called to free any allocated memory.
+ *
+ * Returns: %TRUE if the property exists in @set, %FALSE otherwise
+ *
+ * Since: 3.0
+ **/
 gboolean
 gtk_style_set_get_property (GtkStyleSet   *set,
                             const gchar   *property,
@@ -705,6 +809,16 @@ gtk_style_set_get_property (GtkStyleSet   *set,
   return TRUE;
 }
 
+/**
+ * gtk_style_set_get_valist:
+ * @set: a #GtkStyleSet
+ * @state: state to retrieve the property values for
+ * @args: va_list of property name/return location pairs, followed by %NULL
+ *
+ * Retrieves several style property values from @set for a given state.
+ *
+ * Since: 3.0
+ **/
 void
 gtk_style_set_get_valist (GtkStyleSet   *set,
                           GtkStateFlags  state,
@@ -770,6 +884,17 @@ gtk_style_set_get_valist (GtkStyleSet   *set,
     }
 }
 
+/**
+ * gtk_style_set_get:
+ * @set: a #GtkStyleSet
+ * @state: state to retrieve the property values for
+ * @...: property name /return value pairs, followed by %NULL
+ *
+ * Retrieves several style property values from @set for a
+ * given state.
+ *
+ * Since: 3.0
+ **/
 void
 gtk_style_set_get (GtkStyleSet   *set,
                    GtkStateFlags  state,
@@ -784,6 +909,16 @@ gtk_style_set_get (GtkStyleSet   *set,
   va_end (args);
 }
 
+/**
+ * gtk_style_set_unset_property:
+ * @set: a #GtkStyleSet
+ * @property: property to unset
+ * @state: state to unset
+ *
+ * Unsets a style property in @set.
+ *
+ * Since: 3.0
+ **/
 void
 gtk_style_set_unset_property (GtkStyleSet   *set,
                               const gchar   *property,
@@ -825,6 +960,12 @@ gtk_style_set_unset_property (GtkStyleSet   *set,
     }
 }
 
+/**
+ * gtk_style_set_clear:
+ * @set: a #GtkStyleSet
+ *
+ * Clears all style information from @set.
+ **/
 void
 gtk_style_set_clear (GtkStyleSet *set)
 {
@@ -836,6 +977,19 @@ gtk_style_set_clear (GtkStyleSet *set)
   g_hash_table_remove_all (priv->properties);
 }
 
+/**
+ * gtk_style_set_merge:
+ * @set: a #GtkStyleSet
+ * @set_to_merge: a second #GtkStyleSet
+ * @replace: whether to replace values or not
+ *
+ * Merges into @set all the style information contained
+ * in @set_to_merge. If @replace is %TRUE, the values
+ * will be overwritten, if it is %FALSE, the older values
+ * will prevail.
+ *
+ * Since: 3.0
+ **/
 void
 gtk_style_set_merge (GtkStyleSet       *set,
                      const GtkStyleSet *set_to_merge,
diff --git a/gtk/gtkstyleset.h b/gtk/gtkstyleset.h
index f81881a..f19ce16 100644
--- a/gtk/gtkstyleset.h
+++ b/gtk/gtkstyleset.h
@@ -34,16 +34,16 @@ G_BEGIN_DECLS
 #define GTK_IS_STYLE_SET_CLASS(c)  (G_TYPE_CHECK_CLASS_TYPE    ((c), GTK_TYPE_STYLE_SET))
 #define GTK_STYLE_SET_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS  ((o), GTK_TYPE_STYLE_SET, GtkStyleSetClass))
 
-typedef struct GtkStyleSet GtkStyleSet;
-typedef struct GtkStyleSetClass GtkStyleSetClass;
+typedef struct _GtkStyleSet GtkStyleSet;
+typedef struct _GtkStyleSetClass GtkStyleSetClass;
 
-struct GtkStyleSet
+struct _GtkStyleSet
 {
   GObject parent_object;
   gpointer priv;
 };
 
-struct GtkStyleSetClass
+struct _GtkStyleSetClass
 {
   GObjectClass parent_class;
 };
diff --git a/gtk/gtksymboliccolor.c b/gtk/gtksymboliccolor.c
index 657ac82..e803c2e 100644
--- a/gtk/gtksymboliccolor.c
+++ b/gtk/gtksymboliccolor.c
@@ -35,7 +35,7 @@ typedef enum {
   COLOR_TYPE_MIX
 } ColorType;
 
-struct GtkSymbolicColor
+struct _GtkSymbolicColor
 {
   ColorType type;
   guint ref_count;
@@ -68,7 +68,7 @@ struct ColorStop
   GtkSymbolicColor *color;
 };
 
-struct GtkGradient
+struct _GtkGradient
 {
   gdouble x0;
   gdouble y0;
@@ -82,6 +82,16 @@ struct GtkGradient
   guint ref_count;
 };
 
+/**
+ * gtk_symbolic_color_new_literal:
+ * @color: a #GdkColor
+ *
+ * Creates a symbolic color pointing to a literal color.
+ *
+ * Returns: a newly created #GtkSymbolicColor
+ *
+ * Since: 3.0
+ **/
 GtkSymbolicColor *
 gtk_symbolic_color_new_literal (GdkColor *color)
 {
@@ -97,6 +107,18 @@ gtk_symbolic_color_new_literal (GdkColor *color)
   return symbolic_color;
 }
 
+/**
+ * gtk_symbolic_color_new_name:
+ * @name: color name
+ *
+ * Creates a symbolic color pointing to an unresolved named
+ * color. See gtk_style_context_lookup_color() and
+ * gtk_style_set_lookup_color().
+ *
+ * Returns: a newly created #GtkSymbolicColor
+ *
+ * Since: 3.0
+ **/
 GtkSymbolicColor *
 gtk_symbolic_color_new_name (const gchar *name)
 {
@@ -112,6 +134,20 @@ gtk_symbolic_color_new_name (const gchar *name)
   return symbolic_color;
 }
 
+/**
+ * gtk_symbolic_color_new_shade:
+ * @color: another #GtkSymbolicColor
+ * @factor: shading factor to apply to @color
+ *
+ * Creates a symbolic color defined as a shade of
+ * another color. A factor > 1.0 would resolve to
+ * a brighter color, while < 1.0 would resolve to
+ * a darker color.
+ *
+ * Returns: A newly created #GtkSymbolicColor
+ *
+ * Since: 3.0
+ **/
 GtkSymbolicColor *
 gtk_symbolic_color_new_shade (GtkSymbolicColor *color,
                               gdouble           factor)
@@ -129,6 +165,20 @@ gtk_symbolic_color_new_shade (GtkSymbolicColor *color,
   return symbolic_color;
 }
 
+/**
+ * gtk_symbolic_color_new_mix:
+ * @color1: color to mix
+ * @color2: another color to mix
+ * @factor: mix factor
+ *
+ * Creates a symbolic color defined as a mix of another
+ * two colors. a mix factor of 0 would resolve to @color1,
+ * while a factor of 1 would resolve to @color2.
+ *
+ * Returns: A newly created #GtkSymbolicColor
+ *
+ * Since: 3.0
+ **/
 GtkSymbolicColor *
 gtk_symbolic_color_new_mix (GtkSymbolicColor *color1,
                             GtkSymbolicColor *color2,
@@ -149,6 +199,16 @@ gtk_symbolic_color_new_mix (GtkSymbolicColor *color1,
   return symbolic_color;
 }
 
+/**
+ * gtk_symbolic_color_ref:
+ * @color: a #GtkSymbolicColor
+ *
+ * Increases the reference count of @color
+ *
+ * Returns: the same @color
+ *
+ * Since: 3.0
+ **/
 GtkSymbolicColor *
 gtk_symbolic_color_ref (GtkSymbolicColor *color)
 {
@@ -159,6 +219,15 @@ gtk_symbolic_color_ref (GtkSymbolicColor *color)
   return color;
 }
 
+/**
+ * gtk_symbolic_color_unref:
+ * @color: a #GtkSymbolicColor
+ *
+ * Decreases the reference count of @color, freeing its memory if the
+ * reference count reaches 0.
+ *
+ * Since: 3.0
+ **/
 void
 gtk_symbolic_color_unref (GtkSymbolicColor *color)
 {
@@ -188,6 +257,21 @@ gtk_symbolic_color_unref (GtkSymbolicColor *color)
     }
 }
 
+/**
+ * gtk_symbolic_color_resolve:
+ * @color: a #GtkSymbolicColor
+ * @style_set: #GtkStyleSet to use when resolving named colors
+ * @resolved_color: (out): return location for the resolved color
+ *
+ * If @color is resolvable, @resolved_color will be filled in
+ * with the resolved color, and %TRUE will be returned. Generally,
+ * if @color can't be resolved, it is due to it being defined on
+ * top of a named color that doesn't exist in @style_set.
+ *
+ * Returns: %TRUE if the color has been resolved
+ *
+ * Since: 3.0
+ **/
 gboolean
 gtk_symbolic_color_resolve (GtkSymbolicColor    *color,
                             GtkStyleSet         *style_set,
@@ -256,6 +340,20 @@ gtk_symbolic_color_resolve (GtkSymbolicColor    *color,
 }
 
 /* GtkGradient */
+/**
+ * gtk_gradient_new_linear:
+ * @x0: X coordinate of the starting point
+ * @y0: Y coordinate of the starting point
+ * @x1: X coordinate of the end point
+ * @y1: Y coordinate of the end point
+ *
+ * Creates a new linear gradient along the line defined by (x0, y0) and (x1, y1). Before using the gradient
+ * a number of stop colors must be added through gtk_gradient_add_color_stop().
+ *
+ * Returns: A newly created #GtkGradient
+ *
+ * Since: 3.0
+ **/
 GtkGradient *
 gtk_gradient_new_linear (gdouble x0,
                          gdouble y0,
@@ -279,6 +377,23 @@ gtk_gradient_new_linear (gdouble x0,
   return gradient;
 }
 
+/**
+ * gtk_gradient_new_radial:
+ * @x0: X coordinate of the start circle
+ * @y0: Y coordinate of the start circle
+ * @radius0: radius of the start circle
+ * @x1: X coordinate of the end circle
+ * @y1: Y coordinate of the end circle
+ * @radius1: radius of the end circle
+ *
+ * Creates a new radial gradient along the two circles defined by (x0, y0, radius0) and
+ * (x1, y1, radius1). Before using the gradient a number of stop colors must be added
+ * through gtk_gradient_add_color_stop().
+ *
+ * Returns: A newly created #GtkGradient
+ *
+ * Since: 3.0
+ **/
 GtkGradient *
 gtk_gradient_new_radial (gdouble x0,
 			 gdouble y0,
@@ -304,6 +419,16 @@ gtk_gradient_new_radial (gdouble x0,
   return gradient;
 }
 
+/**
+ * gtk_gradient_add_color_stop:
+ * @gradient: a #GtkGradient
+ * @offset: offset for the color stop
+ * @color: color to use
+ *
+ * Adds a stop color to @gradient.
+ *
+ * Since: 3.0
+ **/
 void
 gtk_gradient_add_color_stop (GtkGradient      *gradient,
                              gdouble           offset,
@@ -319,6 +444,16 @@ gtk_gradient_add_color_stop (GtkGradient      *gradient,
   g_array_append_val (gradient->stops, stop);
 }
 
+/**
+ * gtk_gradient_ref:
+ * @gradient: a #GtkGradient
+ *
+ * Increases the reference count of @gradient.
+ *
+ * Returns: The same @gradient
+ *
+ * Since: 3.0
+ **/
 GtkGradient *
 gtk_gradient_ref (GtkGradient *gradient)
 {
@@ -329,6 +464,15 @@ gtk_gradient_ref (GtkGradient *gradient)
   return gradient;
 }
 
+/**
+ * gtk_gradient_unref:
+ * @gradient: a #GtkGradient
+ *
+ * Decreases the reference count of @gradient, freeing its memory
+ * if the reference count reaches 0.
+ *
+ * Since: 3.0
+ **/
 void
 gtk_gradient_unref (GtkGradient *gradient)
 {
@@ -353,6 +497,22 @@ gtk_gradient_unref (GtkGradient *gradient)
     }
 }
 
+/**
+ * gtk_gradient_resolve:
+ * @gradient: a #GtkGradient
+ * @style_set: #GtkStyleSet to use when resolving named colors
+ * @resolved_gradient: (out): return location for the resolved pattern
+ *
+ * If @gradient is resolvable, @resolved_gradient will be filled in
+ * with the resolved gradient as a cairo_pattern_t, and %TRUE will
+ * be returned. Generally, if @gradient can't be resolved, it is
+ * due to it being defined on top of a named color that doesn't
+ * exist in @style_set.
+ *
+ * Returns: %TRUE if the gradient has been resolved
+ *
+ * Since: 3.0
+ **/
 gboolean
 gtk_gradient_resolve (GtkGradient      *gradient,
                       GtkStyleSet      *style_set,
diff --git a/gtk/gtksymboliccolor.h b/gtk/gtksymboliccolor.h
index de403a3..e326992 100644
--- a/gtk/gtksymboliccolor.h
+++ b/gtk/gtksymboliccolor.h
@@ -25,8 +25,8 @@
 G_BEGIN_DECLS
 
 /* Dummy typedefs */
-typedef struct GtkSymbolicColor GtkSymbolicColor;
-typedef struct GtkGradient GtkGradient;
+typedef struct _GtkSymbolicColor GtkSymbolicColor;
+typedef struct _GtkGradient GtkGradient;
 
 #define GTK_TYPE_SYMBOLIC_COLOR (gtk_symbolic_color_get_type ())
 #define GTK_TYPE_GRADIENT (gtk_gradient_get_type ())
diff --git a/gtk/gtkthemingengine.c b/gtk/gtkthemingengine.c
index 5096996..f72e6a6 100644
--- a/gtk/gtkthemingengine.c
+++ b/gtk/gtkthemingengine.c
@@ -29,6 +29,23 @@
 #include "gtk9slice.h"
 #include "gtkpango.h"
 
+/**
+ * SECTION:gtkthemingengine
+ * @Short_description: Theming renderers
+ * @Title: GtkThemingEngine
+ * @See_also: #GtkStyleContext
+ *
+ * #GtkThemingEngine is the object used for rendering themed content
+ * in GTK+ widgets. Even though GTK+ has a default implementation,
+ * it can be overridden in CSS files by enforcing a #GtkThemingEngine
+ * object to be loaded as a module.
+ *
+ * In order to implement a theming engine, a #GtkThemingEngine subclass
+ * must be created, alongside the CSS file that will reference it, the
+ * theming engine would be created as an .so library, and installed in
+ * $(gtk-modules-dir)/theming-engines/.
+ */
+
 typedef struct GtkThemingEnginePrivate GtkThemingEnginePrivate;
 
 enum {
@@ -194,6 +211,45 @@ _gtk_theming_engine_set_context (GtkThemingEngine *engine,
   priv->context = context;
 }
 
+/**
+ * gtk_theming_engine_register_property:
+ * @engine: a #GtkThemingEngine
+ * @property_name: property name to register
+ * @type: #GType the property will hold
+ * @default_value: default value for this property
+ * @parse_func: parsing function to use, or %NULL
+ *
+ * Registers a property so it can be used in the CSS file format,
+ * on the CSS file the property will look like
+ * "-${engine-object-name}-${ property_name}". being
+ * ${engine-object-name} the same than G_OBJECT_TYPE_NAME(engine)
+ * would return.
+ *
+ * For any type a @parse_func may be provided, being this function
+ * used for turning any property value (between ':' and ';') in
+ * CSS to the #GValue needed. For basic types there is already
+ * builtin parsing support, so %NULL may be provided for these
+ * cases.
+ *
+ * <note>
+ * This function needs to be called only once during theming
+ * engine object initialization.
+ * </note>
+ *
+ * <note>
+ * In order to make use of the custom registered properties in
+ * the CSS file, make sure the engine is loaded first either in
+ * a previous rule or within the same one.
+ * <programlisting>
+ * &ast; {
+ *     engine: someengine;
+ *     SomeEngine-custom-property: 2;
+ * }
+ * </programlisting>
+ * </note>
+ *
+ * Since: 3.0
+ **/
 void
 gtk_theming_engine_register_property (GtkThemingEngine       *engine,
                                       const gchar            *property_name,
@@ -213,6 +269,20 @@ gtk_theming_engine_register_property (GtkThemingEngine       *engine,
   g_free (name);
 }
 
+/**
+ * gtk_theming_engine_get_property:
+ * @engine: a #GtkThemingEngine
+ * @property: the property name
+ * @state: state to retrieve the value for
+ * @value: (out) (transfer full): return location for the property value,
+ *         you must free this memory using g_value_unset() once you are
+ *         done with it.
+ *
+ * Gets a property value as retrieved from the style settings that apply
+ * to the currently rendered element.
+ *
+ * Since: 3.0
+ **/
 void
 gtk_theming_engine_get_property (GtkThemingEngine *engine,
                                  const gchar      *property,
@@ -229,6 +299,17 @@ gtk_theming_engine_get_property (GtkThemingEngine *engine,
   gtk_style_context_get_property (priv->context, property, state, value);
 }
 
+/**
+ * gtk_theming_engine_get_valist:
+ * @engine: a #GtkThemingEngine
+ * @state: state to retrieve values for
+ * @args: va_list of property name/return location pairs, followed by %NULL
+ *
+ * Retrieves several style property values that apply to the currently
+ * rendered element.
+ *
+ * Since: 3.0
+ **/
 void
 gtk_theming_engine_get_valist (GtkThemingEngine *engine,
                                GtkStateFlags     state,
@@ -242,6 +323,17 @@ gtk_theming_engine_get_valist (GtkThemingEngine *engine,
   gtk_style_context_get_valist (priv->context, state, args);
 }
 
+/**
+ * gtk_theming_engine_get:
+ * @engine: a #GtkThemingEngine
+ * @state: state to retrieve values for
+ * @...: property name /return value pairs, followed by %NULL
+ *
+ * Retrieves several style property values that apply to the currently
+ * rendered element.
+ *
+ * Since: 3.0
+ **/
 void
 gtk_theming_engine_get (GtkThemingEngine *engine,
                         GtkStateFlags     state,
@@ -259,6 +351,17 @@ gtk_theming_engine_get (GtkThemingEngine *engine,
   va_end (args);
 }
 
+/**
+ * gtk_theming_engine_get_style_property:
+ * @engine: a #GtkThemingEngine
+ * @property_name: the name of the widget style property
+ * @value: (out) (transfer full): Return location for the property value, free with
+ *         g_value_unset() after use.
+ *
+ * Gets the value for a widget style property.
+ *
+ * Since: 3.0
+ **/
 void
 gtk_theming_engine_get_style_property (GtkThemingEngine *engine,
                                        const gchar      *property_name,
@@ -273,6 +376,16 @@ gtk_theming_engine_get_style_property (GtkThemingEngine *engine,
   gtk_style_context_get_style_property (priv->context, property_name, value);
 }
 
+/**
+ * gtk_theming_engine_get_style_valist:
+ * @engine: a #GtkThemingEngine
+ * @args: va_list of property name/return location pairs, followed by %NULL
+ *
+ * Retrieves several widget style properties from @engine according to the
+ * currently rendered content's style.
+ *
+ * Since: 3.0
+ **/
 void
 gtk_theming_engine_get_style_valist (GtkThemingEngine *engine,
                                      va_list           args)
@@ -285,6 +398,16 @@ gtk_theming_engine_get_style_valist (GtkThemingEngine *engine,
   gtk_style_context_get_style_valist (priv->context, args);
 }
 
+/**
+ * gtk_theming_engine_get_style:
+ * @engine: a #GtkThemingEngine
+ * @...: property name /return value pairs, followed by %NULL
+ *
+ * Retrieves several widget style properties from @engine according
+ * to the currently rendered content's style.
+ *
+ * Since: 3.0
+ **/
 void
 gtk_theming_engine_get_style (GtkThemingEngine *engine,
                               ...)
@@ -301,6 +424,16 @@ gtk_theming_engine_get_style (GtkThemingEngine *engine,
   va_end (args);
 }
 
+/**
+ * gtk_theming_engine_get_state:
+ * @engine: a #GtkThemingEngine
+ *
+ * returns the state used when rendering.
+ *
+ * Returns: the state flags
+ *
+ * Since: 3.0
+ **/
 GtkStateFlags
 gtk_theming_engine_get_state (GtkThemingEngine *engine)
 {
@@ -325,6 +458,16 @@ gtk_theming_engine_is_state_set (GtkThemingEngine *engine,
   return gtk_style_context_is_state_set (priv->context, state, progress);
 }
 
+/**
+ * gtk_theming_engine_get_path:
+ * @engine: a #GtkThemingEngine
+ *
+ * Returns the widget path used for style matching.
+ *
+ * Returns: (transfer none): A #GtkWidgetPath
+ *
+ * Since: 3.0
+ **/
 G_CONST_RETURN GtkWidgetPath *
 gtk_theming_engine_get_path (GtkThemingEngine *engine)
 {
@@ -336,6 +479,18 @@ gtk_theming_engine_get_path (GtkThemingEngine *engine)
   return gtk_style_context_get_path (priv->context);
 }
 
+/**
+ * gtk_theming_engine_has_class:
+ * @engine: a #GtkThemingEngine
+ * @style_class: class name to look up
+ *
+ * Returns %TRUE if the currently rendered contents have
+ * defined the given class name.
+ *
+ * Returns: %TRUE if @engine has @class_name defined
+ *
+ * Since: 3.0
+ **/
 gboolean
 gtk_theming_engine_has_class (GtkThemingEngine *engine,
                               const gchar      *style_class)
@@ -348,9 +503,23 @@ gtk_theming_engine_has_class (GtkThemingEngine *engine,
   return gtk_style_context_has_class (priv->context, style_class);
 }
 
+/**
+ * gtk_theming_engine_has_region:
+ * @engine: a #GtkThemingEngine
+ * @style_region: a region name
+ * @flags: (out) (allow-none): return location for region flags
+ *
+ * Returns %TRUE if the currently rendered contents have the
+ * region defined. If @flags_return is not %NULL, it is set
+ * to the flags affecting the region.
+ *
+ * Returns: %TRUE if region is defined
+ *
+ * Since: 3.0
+ **/
 gboolean
 gtk_theming_engine_has_region (GtkThemingEngine *engine,
-                               const gchar      *style_class,
+                               const gchar      *style_region,
                                GtkRegionFlags   *flags)
 {
   GtkThemingEnginePrivate *priv;
@@ -361,9 +530,19 @@ gtk_theming_engine_has_region (GtkThemingEngine *engine,
   g_return_val_if_fail (GTK_IS_THEMING_ENGINE (engine), FALSE);
 
   priv = engine->priv;
-  return gtk_style_context_has_region (priv->context, style_class, flags);
+  return gtk_style_context_has_region (priv->context, style_region, flags);
 }
 
+/**
+ * gtk_theming_engine_get_direction:
+ * @engine: a #GtkThemingEngine
+ *
+ * Returns the widget direction used for rendering.
+ *
+ * Returns: the widget direction
+ *
+ * Since: 3.0
+ **/
 GtkTextDirection
 gtk_theming_engine_get_direction (GtkThemingEngine *engine)
 {
@@ -375,6 +554,16 @@ gtk_theming_engine_get_direction (GtkThemingEngine *engine)
   return gtk_style_context_get_direction (priv->context);
 }
 
+/**
+ * gtk_theming_engine_get_junction_sides:
+ * @engine: a #GtkThemingEngine
+ *
+ * Returns the widget direction used for rendering.
+ *
+ * Returns: the widget direction
+ *
+ * Since: 3.0
+ **/
 GtkJunctionSides
 gtk_theming_engine_get_junction_sides (GtkThemingEngine *engine)
 {
@@ -441,6 +630,16 @@ gtk_theming_module_init (GtkThemingModule *module)
 {
 }
 
+/**
+ * gtk_theming_engine_load:
+ * @name: Theme engine name to load
+ *
+ * Loads and initializes a theming engine module from the
+ * standard directories.
+ *
+ * Returns: (transfer none): A theming engine, or %NULL if
+ * the engine @name doesn't exist.
+ **/
 GtkThemingEngine *
 gtk_theming_engine_load (const gchar *name)
 {
@@ -484,6 +683,14 @@ gtk_theming_engine_load (const gchar *name)
   return engine;
 }
 
+/**
+ * gtk_theming_engine_get_screen:
+ * @engine: a #GtkThemingEngine
+ *
+ * Returns the #GdkScreen to which @engine currently rendering to.
+ *
+ * Returns: a #GdkScreen, or %NULL.
+ **/
 GdkScreen *
 gtk_theming_engine_get_screen (GtkThemingEngine *engine)
 {
diff --git a/gtk/gtkthemingengine.h b/gtk/gtkthemingengine.h
index 47a4234..6ecf9c1 100644
--- a/gtk/gtkthemingengine.h
+++ b/gtk/gtkthemingengine.h
@@ -36,16 +36,36 @@ G_BEGIN_DECLS
 #define GTK_IS_THEMING_ENGINE_CLASS(c)  (G_TYPE_CHECK_CLASS_TYPE    ((c), GTK_TYPE_THEMING_ENGINE))
 #define GTK_THEMING_ENGINE_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS  ((o), GTK_TYPE_THEMING_ENGINE, GtkThemingEngineClass))
 
-typedef struct GtkThemingEngine GtkThemingEngine;
-typedef struct GtkThemingEngineClass GtkThemingEngineClass;
+typedef struct _GtkThemingEngine GtkThemingEngine;
+typedef struct _GtkThemingEngineClass GtkThemingEngineClass;
 
-struct GtkThemingEngine
+struct _GtkThemingEngine
 {
   GObject parent_object;
   gpointer priv;
 };
 
-struct GtkThemingEngineClass
+/**
+ * GtkThemingEngineClass
+ * @parent_class: The parent class.
+ * @render_line: Renders a line between two points.
+ * @render_background: Renders the background area of a widget region.
+ * @render_frame: Renders the frame around a widget area.
+ * @render_frame_gap: Renders the frame around a widget area with a gap in it.
+ * @render_extension: Renders a extension to a box, usually a notebook tab.
+ * @render_check: Renders a checkmark, as in #GtkCheckButton.
+ * @render_option: Renders an option, as in #GtkRadioButton.
+ * @render_arrow: Renders an arrow pointing to a certain direction.
+ * @render_expander: Renders an element what will expose/expand part of
+ *                   the UI, as in #GtkExpander.
+ * @render_focus: Renders the focus indicator.
+ * @render_layout: Renders a #PangoLayout
+ * @render_slider: Renders a slider control, as in #GtkScale.
+ * @render_handle: Renders a handle to drag UI elements, as in #GtkPaned.
+ *
+ * Base class for theming engines.
+ */
+struct _GtkThemingEngineClass
 {
   GObjectClass parent_class;
 
diff --git a/gtk/gtkwidget.c b/gtk/gtkwidget.c
index 4fa3acf..a2e4437 100644
--- a/gtk/gtkwidget.c
+++ b/gtk/gtkwidget.c
@@ -12620,6 +12620,16 @@ _gtk_widget_set_height_request_needed (GtkWidget *widget,
   widget->priv->height_request_needed = height_request_needed;
 }
 
+/**
+ * gtk_widget_get_path:
+ * @widget: a #GtkWidget
+ *
+ * Returns the #GtkWidgetPath representing @widget, if the widget
+ * is not connected to a toplevel widget, a partial path will be
+ * created.
+ *
+ * Returns: (transfer none): The #GtkWidgetPath representing @widget
+ **/
 GtkWidgetPath *
 gtk_widget_get_path (GtkWidget *widget)
 {
@@ -12662,6 +12672,15 @@ style_context_changed (GtkStyleContext *context,
   g_signal_emit (widget, widget_signals[STYLE_UPDATED], 0);
 }
 
+/**
+ * gtk_widget_get_style_context:
+ * @widget: a #GtkWidget
+ *
+ * Returns the style context associated to @widget.
+ *
+ * Returns: (transfer none): a #GtkStyleContext. This memory is owned by @widget and
+ *          must not be freed.
+ **/
 GtkStyleContext *
 gtk_widget_get_style_context (GtkWidget *widget)
 {
diff --git a/gtk/gtkwidgetpath.c b/gtk/gtkwidgetpath.c
index c6cfbb5..578335b 100644
--- a/gtk/gtkwidgetpath.c
+++ b/gtk/gtkwidgetpath.c
@@ -24,6 +24,62 @@
 #include "gtkwidget.h"
 #include "gtkwidgetpath.h"
 
+/**
+ * SECTION:gtkwidgetpath
+ * @Short_description: Widget path abstraction
+ * @Title: GtkWidgetPath
+ * @See_also: #GtkStyleContext
+ *
+ * #GtkWidgetPath is an struct that represents a widget hierarchy from
+ * the topmost widget, typically a toplevel, to any child. This widget
+ * path abstraction is used in #GtkStyleContext on behalf of the real
+ * widget in order to query style information.
+ *
+ * If you are using GTK+ widgets, there are many chances you don't
+ * need this API directly, as there is gtk_widget_get_path(), and the
+ * style context returned by gtk_widget_get_style_context() will be
+ * automatically updated on widget hierarchy changes.
+ *
+ * The widget path generation is generally simple:
+ * <example>
+ * <title>Defining a button within a window</title>
+ * <programlisting>
+ * {
+ *   GtkWidgetPath *path;
+ *
+ *   path = gtk_widget_path_new ();
+ *   gtk_widget_path_append_type (path, GTK_TYPE_WINDOW);
+ *   gtk_widget_path_append_type (path, GTK_TYPE_BUTTON);
+ * }
+ * </programlisting>
+ * </example>
+ *
+ * Although more complex information, such as widget names, or
+ * different classes (property that may be used by other widget
+ * types) and intermediate regions may be included:
+ *
+ * <example>
+ * <title>Defining the first tab widget in a notebook</title>
+ * <programlisting>
+ * {
+ *   GtkWidgetPath *path;
+ *   guint pos;
+ *
+ *   path = gtk_widget_path_new ();
+ *
+ *   pos = gtk_widget_path_append_type (path, GTK_TYPE_NOTEBOOK);
+ *   gtk_widget_path_iter_add_region (path, pos, "tab", GTK_REGION_EVEN | GTK_REGION_FIRST);
+ *
+ *   pos = gtk_widget_path_append_type (path, GTK_TYPE_LABEL);
+ *   gtk_widget_path_iter_set_name (path, pos, "first tab label");
+ * }
+ * </programlisting>
+ * </example>
+ *
+ * All this information will be used to match the style information
+ * that applies to the described widget.
+ **/
+
 typedef struct GtkPathElement GtkPathElement;
 
 struct GtkPathElement
@@ -34,11 +90,20 @@ struct GtkPathElement
   GArray *classes;
 };
 
-struct GtkWidgetPath
+struct _GtkWidgetPath
 {
   GArray *elems; /* First element contains the described widget */
 };
 
+/**
+ * gtk_widget_path_new:
+ *
+ * Returns an empty widget path.
+ *
+ * Returns: (transfer full): A newly created, empty, #GtkWidgetPath
+ *
+ * Since: 3.0
+ **/
 GtkWidgetPath *
 gtk_widget_path_new (void)
 {
@@ -50,6 +115,16 @@ gtk_widget_path_new (void)
   return path;
 }
 
+/**
+ * gtk_widget_path_copy:
+ * @path: a #GtkWidgetPath
+ *
+ * Returns a copy of @path
+ *
+ * Returns: (transfer full): a copy of @path
+ *
+ * Since: 3.0
+ **/
 GtkWidgetPath *
 gtk_widget_path_copy (const GtkWidgetPath *path)
 {
@@ -87,6 +162,14 @@ gtk_widget_path_copy (const GtkWidgetPath *path)
   return new_path;
 }
 
+/**
+ * gtk_widget_path_free:
+ * @path: a #GtkWidgetPath
+ *
+ * Frees a #GtkWidgetPath.
+ *
+ * Since: 3.0
+ **/
 void
 gtk_widget_path_free (GtkWidgetPath *path)
 {
@@ -111,6 +194,17 @@ gtk_widget_path_free (GtkWidgetPath *path)
   g_slice_free (GtkWidgetPath, path);
 }
 
+/**
+ * gtk_widget_path_length:
+ * @path: a #GtkWidgetPath
+ *
+ * Returns the number of #GtkWidget #GTypes between the represented
+ * widget and its topmost container.
+ *
+ * Returns: the number of elements in the path
+ *
+ * Since: 3.0
+ **/
 guint
 gtk_widget_path_length (const GtkWidgetPath *path)
 {
@@ -119,6 +213,17 @@ gtk_widget_path_length (const GtkWidgetPath *path)
   return path->elems->len;
 }
 
+/**
+ * gtk_widget_path_prepend_type:
+ * @path: a #GtkWidgetPath
+ * @type: widget type to prepend
+ *
+ * Prepends a widget type to the widget hierachy represented by @path.
+ *
+ * Returns: the position where the element was inserted
+ *
+ * Since: 3.0
+ **/
 guint
 gtk_widget_path_prepend_type (GtkWidgetPath *path,
                               GType          type)
@@ -134,6 +239,17 @@ gtk_widget_path_prepend_type (GtkWidgetPath *path,
   return 0;
 }
 
+/**
+ * gtk_widget_path_append_type:
+ * @path: a #GtkWidgetPath
+ * @type: widget type to append
+ *
+ * Appends a widget type to the widget hierachy represented by @path.
+ *
+ * Returns: the position where the element was inserted
+ *
+ * Since: 3.0
+ **/
 guint
 gtk_widget_path_append_type (GtkWidgetPath *path,
                              GType          type)
@@ -149,6 +265,18 @@ gtk_widget_path_append_type (GtkWidgetPath *path,
   return path->elems->len - 1;
 }
 
+/**
+ * gtk_widget_path_iter_get_widget_type:
+ * @path: a #GtkWidgetPath
+ * @pos: position to get the widget type for
+ *
+ * Returns the widget #GType that is at position @pos in the widget
+ * hierarchy defined in @path.
+ *
+ * Returns: a widget type
+ *
+ * Since: 3.0
+ **/
 GType
 gtk_widget_path_iter_get_widget_type (const GtkWidgetPath *path,
                                       guint                pos)
@@ -162,6 +290,17 @@ gtk_widget_path_iter_get_widget_type (const GtkWidgetPath *path,
   return elem->type;
 }
 
+/**
+ * gtk_widget_path_iter_set_widget_type:
+ * @path: a #GtkWidgetPath
+ * @pos: position to modify
+ * @type: widget type to set
+ *
+ * Sets the widget type for a given position in the widget hierarchy
+ * defined by @path. @type must be a #GtkWidget derived #GType.
+ *
+ * Since: 3.0
+ **/
 void
 gtk_widget_path_iter_set_widget_type (GtkWidgetPath *path,
                                       guint          pos,
@@ -177,6 +316,17 @@ gtk_widget_path_iter_set_widget_type (GtkWidgetPath *path,
   elem->type = type;
 }
 
+/**
+ * gtk_widget_path_iter_get_name:
+ * @path: a #GtkWidgetPath
+ * @pos: position to get the widget name for
+ *
+ * Returns the name corresponding to the widget found at
+ * the position @pos in the widget hierarchy defined by
+ * @path
+ *
+ * Returns: The widget name, or %NULL if none was set.
+ **/
 G_CONST_RETURN gchar *
 gtk_widget_path_iter_get_name (const GtkWidgetPath *path,
                                guint                pos)
@@ -190,6 +340,17 @@ gtk_widget_path_iter_get_name (const GtkWidgetPath *path,
   return g_quark_to_string (elem->name);
 }
 
+/**
+ * gtk_widget_path_iter_set_name:
+ * @path: a #GtkWidgetPath
+ * @pos: position to modify
+ * @name: widget name
+ *
+ * Sets the widget name for the widget found at position @pos
+ * in the widget hierarchy defined by @path.
+ *
+ * Since: 3.0
+ **/
 void
 gtk_widget_path_iter_set_name (GtkWidgetPath *path,
                                guint          pos,
@@ -206,6 +367,19 @@ gtk_widget_path_iter_set_name (GtkWidgetPath *path,
   elem->name = g_quark_from_string (name);
 }
 
+/**
+ * gtk_widget_path_iter_has_qname:
+ * @path: a #GtkWidgetPath
+ * @pos: position to query
+ * @qname: widget name as a #GQuark
+ *
+ * See gtk_widget_path_iter_has_name(). This is a version
+ * that operates on #GQuark<!-- -->s.
+ *
+ * Returns: %TRUE if the widget at @pos has this name
+ *
+ * Since: 3.0
+ **/
 gboolean
 gtk_widget_path_iter_has_qname (const GtkWidgetPath *path,
                                 guint                pos,
@@ -222,6 +396,19 @@ gtk_widget_path_iter_has_qname (const GtkWidgetPath *path,
   return (elem->name == qname);
 }
 
+/**
+ * gtk_widget_path_iter_has_name:
+ * @path: a #GtkWidgetPath
+ * @pos: position to query
+ * @name: a widget name
+ *
+ * Returns %TRUE if the widget at position @pos has the name @name,
+ * %FALSE otherwise.
+ *
+ * Returns: %TRUE if the widget at @pos has this name
+ *
+ * Since: 3.0
+ **/
 gboolean
 gtk_widget_path_iter_has_name (const GtkWidgetPath *path,
                                guint                pos,
@@ -241,6 +428,18 @@ gtk_widget_path_iter_has_name (const GtkWidgetPath *path,
   return gtk_widget_path_iter_has_qname (path, pos, qname);
 }
 
+/**
+ * gtk_widget_path_iter_add_class:
+ * @path: a #GtkWidget
+ * @pos: position to modify
+ * @name: a class name
+ *
+ * Adds the class @name to the widget at position @pos in
+ * the hierarchy defined in @path. See
+ * gtk_style_context_set_class().
+ *
+ * Since: 3.0
+ **/
 void
 gtk_widget_path_iter_add_class (GtkWidgetPath *path,
                                 guint          pos,
@@ -285,6 +484,17 @@ gtk_widget_path_iter_add_class (GtkWidgetPath *path,
     g_array_append_val (elem->classes, qname);
 }
 
+/**
+ * gtk_widget_path_iter_remove_class:
+ * @path: a #GtkWidgetPath
+ * @pos: position to modify
+ * @name: class name
+ *
+ * Removes the class @name from the widget at position @pos in
+ * the hierarchy defined in @path.
+ *
+ * Since: 3.0
+ **/
 void
 gtk_widget_path_iter_remove_class (GtkWidgetPath *path,
                                    guint          pos,
@@ -324,6 +534,16 @@ gtk_widget_path_iter_remove_class (GtkWidgetPath *path,
     }
 }
 
+/**
+ * gtk_widget_path_iter_clear_classes:
+ * @path: a #GtkWidget
+ * @pos: position to modify
+ *
+ * Removes all classes from the widget at position @pos in the
+ * hierarchy defined in @path.
+ *
+ * Since: 3.0
+ **/
 void
 gtk_widget_path_iter_clear_classes (GtkWidgetPath *path,
                                     guint          pos)
@@ -342,6 +562,21 @@ gtk_widget_path_iter_clear_classes (GtkWidgetPath *path,
     g_array_remove_range (elem->classes, 0, elem->classes->len);
 }
 
+/**
+ * gtk_widget_path_iter_list_classes:
+ * @path: a #GtkWidgetPath
+ * @pos: position to query
+ *
+ * Returns a list with all the class names defined for the widget
+ * at position @pos in the hierarchy defined in @path.
+ *
+ * Returns: (transfer container) (type utf8): The list of classes,
+ *          This is a list of strings, the #GSList contents are
+ *          owned by GTK+, but you should use g_slist_free() to
+ *          free the list itself.
+ *
+ * Since: 3.0
+ **/
 GSList *
 gtk_widget_path_iter_list_classes (const GtkWidgetPath *path,
                                    guint                pos)
@@ -369,6 +604,19 @@ gtk_widget_path_iter_list_classes (const GtkWidgetPath *path,
   return g_slist_reverse (list);
 }
 
+/**
+ * gtk_widget_path_iter_has_qclass:
+ * @path: a #GtkWidgetPath
+ * @pos: position to query
+ * @qname: class name as a #GQuark
+ *
+ * See gtk_widget_path_iter_has_class(). This is a version that operates
+ * with GQuark<!-- -->s.
+ *
+ * Returns: %TRUE if the widget at @pos has the class defined.
+ *
+ * Since: 3.0
+ **/
 gboolean
 gtk_widget_path_iter_has_qclass (const GtkWidgetPath *path,
                                  guint                pos,
@@ -401,6 +649,19 @@ gtk_widget_path_iter_has_qclass (const GtkWidgetPath *path,
   return FALSE;
 }
 
+/**
+ * gtk_widget_path_iter_has_class:
+ * @path: a #GtkWidgetPath
+ * @pos: position to query
+ * @name: class name
+ *
+ * Returns %TRUE if the widget at position @pos has the class @name
+ * defined, %FALSE otherwise.
+ *
+ * Returns: %TRUE if the class @name is defined for the widget at @pos
+ *
+ * Since: 3.0
+ **/
 gboolean
 gtk_widget_path_iter_has_class (const GtkWidgetPath *path,
                                 guint                pos,
@@ -420,6 +681,19 @@ gtk_widget_path_iter_has_class (const GtkWidgetPath *path,
   return gtk_widget_path_iter_has_qclass (path, pos, qname);
 }
 
+/**
+ * gtk_widget_path_iter_add_region:
+ * @path: a #GtkWidgetPath
+ * @pos: position to modify
+ * @name: region name
+ * @flags: flags affecting the region
+ *
+ * Adds the region @name to the widget at position @pos in
+ * the hierarchy defined in @path. See
+ * gtk_style_context_set_region().
+ *
+ * Since: 3.0
+ **/
 void
 gtk_widget_path_iter_add_region (GtkWidgetPath  *path,
                                  guint           pos,
@@ -444,6 +718,17 @@ gtk_widget_path_iter_add_region (GtkWidgetPath  *path,
                        GUINT_TO_POINTER (flags));
 }
 
+/**
+ * gtk_widget_path_iter_remove_region:
+ * @path: a #GtkWidgetPath
+ * @pos: position to modify
+ * @name: region name
+ *
+ * Removes the region @name from the widget at position @pos in
+ * the hierarchy defined in @path.
+ *
+ * Since: 3.0
+ **/
 void
 gtk_widget_path_iter_remove_region (GtkWidgetPath *path,
                                     guint          pos,
@@ -467,6 +752,16 @@ gtk_widget_path_iter_remove_region (GtkWidgetPath *path,
     g_hash_table_remove (elem->regions, GUINT_TO_POINTER (qname));
 }
 
+/**
+ * gtk_widget_path_iter_clear_regions:
+ * @path: a #GtkWidgetPath
+ * @pos: position to modify
+ *
+ * Removes all regions from the widget at position @pos in the
+ * hierarchy defined in @path.
+ *
+ * Since: 3.0
+ **/
 void
 gtk_widget_path_iter_clear_regions (GtkWidgetPath *path,
                                     guint          pos)
@@ -482,6 +777,21 @@ gtk_widget_path_iter_clear_regions (GtkWidgetPath *path,
     g_hash_table_remove_all (elem->regions);
 }
 
+/**
+ * gtk_widget_path_iter_list_regions:
+ * @path: a #GtkWidgetPath
+ * @pos: position to query
+ *
+ * Returns a list with all the region names defined for the widget
+ * at position @pos in the hierarchy defined in @path.
+ *
+ * Returns: (transfer container) (type utf8): The list of regions,
+ *          This is a list of strings, the #GSList contents are
+ *          owned by GTK+, but you should use g_slist_free() to
+ *          free the list itself.
+ *
+ * Since: 3.0
+ **/
 GSList *
 gtk_widget_path_iter_list_regions (const GtkWidgetPath *path,
                                    guint                pos)
@@ -512,6 +822,20 @@ gtk_widget_path_iter_list_regions (const GtkWidgetPath *path,
   return list;
 }
 
+/**
+ * gtk_widget_path_iter_has_qregion:
+ * @path: a #GtkWidgetPath
+ * @pos: position to query
+ * @qname: region name as a #GQuark
+ * @flags: (out): return location for the region flags
+ *
+ * See gtk_widget_path_iter_has_region(). This is a version that operates
+ * with GQuark<!-- -->s.
+ *
+ * Returns: %TRUE if the widget at @pos has the region defined.
+ *
+ * Since: 3.0
+ **/
 gboolean
 gtk_widget_path_iter_has_qregion (const GtkWidgetPath *path,
                                   guint                pos,
@@ -541,6 +865,20 @@ gtk_widget_path_iter_has_qregion (const GtkWidgetPath *path,
   return TRUE;
 }
 
+/**
+ * gtk_widget_path_iter_has_region:
+ * @path: a #GtkWidgetPath
+ * @pos: position to query
+ * @name: region name
+ * @flags: (out): return location for the region flags
+ *
+ * Returns %TRUE if the widget at position @pos has the class @name
+ * defined, %FALSE otherwise.
+ *
+ * Returns: %TRUE if the class @name is defined for the widget at @pos
+ *
+ * Since: 3.0
+ **/
 gboolean
 gtk_widget_path_iter_has_region (const GtkWidgetPath *path,
                                  guint                pos,
@@ -561,6 +899,17 @@ gtk_widget_path_iter_has_region (const GtkWidgetPath *path,
   return gtk_widget_path_iter_has_qregion (path, pos, qname, flags);
 }
 
+/**
+ * gtk_widget_path_get_widget_type:
+ * @path: a #GtkWidget
+ *
+ * Returns the topmost widget type, that is, the widget type this path
+ * is representing.
+ *
+ * Returns: The widget type
+ *
+ * Since: 3.0
+ **/
 GType
 gtk_widget_path_get_widget_type (const GtkWidgetPath *path)
 {
@@ -568,10 +917,23 @@ gtk_widget_path_get_widget_type (const GtkWidgetPath *path)
 
   g_return_val_if_fail (path != NULL, G_TYPE_INVALID);
 
-  elem = &g_array_index (path->elems, GtkPathElement, 0);
+  elem = &g_array_index (path->elems, GtkPathElement,
+                         path->elems->len - 1);
   return elem->type;
 }
 
+/**
+ * gtk_widget_path_is_type:
+ * @path: a #GtkWidgetPath
+ * @type: widget type to match
+ *
+ * Returns %TRUE if the widget type represented by this path
+ * is @type, or a subtype of it.
+ *
+ * Returns: %TRUE if the widget represented by @path is of type @type
+ *
+ * Since: 3.0
+ **/
 gboolean
 gtk_widget_path_is_type (const GtkWidgetPath *path,
                          GType                type)
@@ -581,7 +943,8 @@ gtk_widget_path_is_type (const GtkWidgetPath *path,
   g_return_val_if_fail (path != NULL, FALSE);
   g_return_val_if_fail (g_type_is_a (type, GTK_TYPE_WIDGET), FALSE);
 
-  elem = &g_array_index (path->elems, GtkPathElement, 0);
+  elem = &g_array_index (path->elems, GtkPathElement,
+                         path->elems->len - 1);
 
   if (elem->type == type ||
       g_type_is_a (elem->type, type))
@@ -590,6 +953,18 @@ gtk_widget_path_is_type (const GtkWidgetPath *path,
   return FALSE;
 }
 
+/**
+ * gtk_widget_path_has_parent:
+ * @path: a #GtkWidgetPath
+ * @type: widget type to check in parents
+ *
+ * Returns %TRUE if any of the parents of the widget represented
+ * in @path is of type @type, or any subtype of it.
+ *
+ * Returns: %TRUE if any parent is of type @type
+ *
+ * Since: 3.0
+ **/
 gboolean
 gtk_widget_path_has_parent (const GtkWidgetPath *path,
                             GType                type)
@@ -599,7 +974,7 @@ gtk_widget_path_has_parent (const GtkWidgetPath *path,
   g_return_val_if_fail (path != NULL, FALSE);
   g_return_val_if_fail (g_type_is_a (type, GTK_TYPE_WIDGET), FALSE);
 
-  for (i = 1; i < path->elems->len; i++)
+  for (i = 0; i < path->elems->len - 1; i++)
     {
       GtkPathElement *elem;
 
diff --git a/gtk/gtkwidgetpath.h b/gtk/gtkwidgetpath.h
index 4e5c476..f36ebcb 100644
--- a/gtk/gtkwidgetpath.h
+++ b/gtk/gtkwidgetpath.h
@@ -25,7 +25,7 @@
 
 G_BEGIN_DECLS
 
-typedef struct GtkWidgetPath GtkWidgetPath;
+typedef struct _GtkWidgetPath GtkWidgetPath;
 
 
 GtkWidgetPath * gtk_widget_path_new (void);



[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]