[gtk+/places-sidebar] Add some missing docs for GtkPlacesSidebar

[Federico Mena Quintero <federico src gnome org>]

commit 26a5391caa4add24b774115e46ad2f2836fb8b05
Author: Federico Mena Quintero <federico gnome org>
Date:   Fri Jan 18 19:28:58 2013 -0600

    Add some missing docs for GtkPlacesSidebar
    
    Signed-off-by: Federico Mena Quintero <federico gnome org>

 gtk/gtkplacessidebar.c |    9 ++++++++-
 gtk/gtkplacessidebar.h |   27 +++++++++++++++++++++++++++
 2 files changed, 35 insertions(+), 1 deletions(-)
---
diff --git a/gtk/gtkplacessidebar.c b/gtk/gtkplacessidebar.c
index 4b9e814..f944fb7 100644
--- a/gtk/gtkplacessidebar.c
+++ b/gtk/gtkplacessidebar.c
@@ -108,7 +108,7 @@
  * While bookmarks are completely in control of the user, the places sidebar also
  * allows individual applications to provide extra shortcut folders that are unique
  * to each application.  For example, a Paint program may want to add a shortcut
- * for a Clipart folder.
+ * for a Clipart folder.  You can do this with gtk_places_sidebar_add_shortcut().
  *
  * To make use of the places sidebar, an application at least needs to connect
  * to the #GtkPlacesSidebar::open-location signal.  This is emitted when the
@@ -3768,6 +3768,13 @@ gtk_places_sidebar_style_set (GtkWidget *widget,
 	update_places (sidebar);
 }
 
+/**
+ * gtk_places_sidebar_new:
+ *
+ * Creates a new #GtkPlacesSidebar widget.  The application should connect
+ * to at least the #GtkPlacesSidebar::open-location signal to be notified
+ * when the user makes a selection in the sidebar.
+ */
 GtkWidget *
 gtk_places_sidebar_new (void)
 {
diff --git a/gtk/gtkplacessidebar.h b/gtk/gtkplacessidebar.h
index 27f626e..15acca9 100644
--- a/gtk/gtkplacessidebar.h
+++ b/gtk/gtkplacessidebar.h
@@ -44,6 +44,33 @@ G_BEGIN_DECLS
 typedef struct _GtkPlacesSidebar GtkPlacesSidebar;
 typedef struct _GtkPlacesSidebarClass GtkPlacesSidebarClass;
 
+/**
+ * GtkPlacesOpenFlags:
+ * @GTK_PLACES_OPEN_NORMAL: This is the default mode that #GtkPlacesSidebar uses if no other flags
+ *  are specified.  It indicates that the calling application should open the selected location
+ *  in the normal way, for example, in the folder view beside the sidebar.
+ * @GTK_PLACES_OPEN_NEW_TAB: When passed to gtk_places_sidebar_set_open_flags(), this indicates
+ *  that the application can open folders selected from the sidebar in new tabs.  This value
+ *  will be passed to the #GtkPlacesSidebar::open-location signal when the user selects
+ *  that a location be opened in a new tab instead of in the standard fashion.
+ * @GTK_PLACES_OPEN_NEW_WINDOW: Similar to @GTK_PLACES_OPEN_NEW_TAB, but indicates that the application
+ *  can open folders in new windows.
+ *
+ * These flags serve two purposes.  First, the application can call gtk_places_sidebar_set_open_flags()
+ * using these flags as a bitmask.  This tells the sidebar that the application is able to open
+ * folders selected from the sidebar in various ways, for example, in new tabs or in new windows in
+ * addition to the normal mode.
+ *
+ * Second, when one of these values gets passed back to the application in the
+ * #GtkPlacesSidebar::open-location signal, it means that the application should
+ * open the selected location in the normal way, in a new tab, or in a new
+ * window.  The sidebar takes care of determining the desired way to open the location,
+ * based on the modifier keys that the user is pressing at the time the selection is made.
+ *
+ * If the application never calls gtk_places_sidebar_set_open_flags(), then the sidebar will only
+ * use #GTK_PLACES_OPEN_NORMAL in the #GtkPlacesSidebar::open-location signal.  This is the
+ * default mode of operation.
+ */
 typedef enum {
   GTK_PLACES_OPEN_NORMAL     = 1 << 0,
   GTK_PLACES_OPEN_NEW_TAB    = 1 << 1,