[gtk+/places-sidebar] Add toplevel docs for the sidebar

[Federico Mena Quintero <federico src gnome org>]

commit 52d07c9148c74f7502c959b268a33fb49a9a7625
Author: Federico Mena Quintero <federico gnome org>
Date:   Fri Jan 18 17:18:25 2013 -0600

    Add toplevel docs for the sidebar
    
    Signed-off-by: Federico Mena Quintero <federico gnome org>

 gtk/gtkfilechooser.c   |    5 ++---
 gtk/gtkplacessidebar.c |   30 ++++++++++++++++++++++++++++++
 2 files changed, 32 insertions(+), 3 deletions(-)
---
diff --git a/gtk/gtkfilechooser.c b/gtk/gtkfilechooser.c
index df794e2..c1d3025 100644
--- a/gtk/gtkfilechooser.c
+++ b/gtk/gtkfilechooser.c
@@ -55,9 +55,8 @@
  *    <varlistentry>
  *       <term>Shortcuts</term>
  *       <listitem>
- *          can be provided by the application or by the underlying filesystem
- *          abstraction (e.g. both the gnome-vfs and the Windows filesystems
- *          provide "Desktop" shortcuts). Shortcuts cannot be modified by the
+ *          can be provided by the application.  For example, a Paint program may
+ *          want to add a shortcut for a Clipart folder.  Shortcuts cannot be modified by the
  *          user.
  *       </listitem>
  *    </varlistentry>
diff --git a/gtk/gtkplacessidebar.c b/gtk/gtkplacessidebar.c
index 3b13d9e..4b9e814 100644
--- a/gtk/gtkplacessidebar.c
+++ b/gtk/gtkplacessidebar.c
@@ -87,6 +87,36 @@
 #include "gtktypebuiltins.h"
 #include "gtkwindow.h"
 
+/**
+ * SECTION:gtkplacessidebar
+ * @Short_description: Sidebar that displays frequently-used places in the file system
+ * @Title: GtkPlacesSidebar
+ * @See_also: #GtkFileChooser
+ *
+ * #GtkPlacesSidebar is a widget that displays a list of frequently-used places in the
+ * file system:  the user's home directory, the user's bookmarks, and volumes and drives.
+ * This widget is used as a sidebar in #GtkFileChooser and may be used by file managers
+ * and similar programs.
+ *
+ * The places sidebar displays drives and volumes, and will automatically mount
+ * or unmount them when the user selects them.
+ *
+ * Applications can hook to various signals in the places sidebar to customize
+ * its behavior.  For example, they can add extra commands to the context menu
+ * of the sidebar.
+ *
+ * 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.
+ *
+ * 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
+ * user selects in the sidebar a location to open.  The application should also
+ * call gtk_places_sidebar_set_location() when it changes the currently-viewed
+ * location.
+ */
+
 #define EJECT_BUTTON_XPAD 6
 #define ICON_CELL_XPAD 6