[gtk+] docs: Inline GtkRecentManager documentation

[Emmanuele Bassi <ebassi src gnome org>]

commit 8eeeb97de6f65e3d6653063e51435a422919d378
Author: Emmanuele Bassi <ebassi gnome org>
Date:   Thu Jul 15 09:10:55 2010 +0100

    docs: Inline GtkRecentManager documentation

 docs/reference/gtk/tmpl/gtkrecentmanager.sgml |  464 -------------------------
 gtk/gtkrecentmanager.c                        |   84 +++++-
 gtk/gtkrecentmanager.h                        |   30 ++-
 3 files changed, 109 insertions(+), 469 deletions(-)
---
diff --git a/gtk/gtkrecentmanager.c b/gtk/gtkrecentmanager.c
index 58b41dc..4226de2 100644
--- a/gtk/gtkrecentmanager.c
+++ b/gtk/gtkrecentmanager.c
@@ -18,6 +18,75 @@
  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  */
 
+/**
+ * SECTION:gtkrecentmanager
+ * @Title: GtkRecentManager
+ * @short_description: Managing recently used files
+ * @See_Also: #GBookmarkFile, #GtkSettings, #GtkRecentChooser
+ *
+ * #GtkRecentManager provides a facility for adding, removing and
+ * looking up recently used files. Each recently used file is
+ * identified by its URI, and has meta-data associated to it, like
+ * the names and command lines of the applications that have
+ * registered it, the number of time each application has registered
+ * the same file, the mime type of the file and whether the file
+ * should be displayed only by the applications that have
+ * registered it.
+ *
+ * <note><para>The recently used files list is per user.</para></note>
+ *
+ * The #GtkRecentManager acts like a database of all the recently
+ * used files. You can create new #GtkRecentManager objects, but
+ * it is more efficient to use the default manager created by GTK+.
+ *
+ * Adding a new recently used file is as simple as:
+ *
+ * |[
+ * GtkRecentManager *manager;
+ *
+ * manager = gtk_recent_manager_get_default ();
+ * gtk_recent_manager_add_item (manager, file_uri);
+ * ]|
+ *
+ * The #GtkRecentManager will try to gather all the needed information
+ * from the file itself through GIO.
+ *
+ * Looking up the meta-data associated with a recently used file
+ * given its URI requires calling gtk_recent_manager_lookup_item():
+ *
+ * |[
+ * GtkRecentManager *manager;
+ * GtkRecentInfo *info;
+ * GError *error = NULL;
+ *
+ * manager = gtk_recent_manager_get_default ();
+ * info = gtk_recent_manager_lookup_item (manager, file_uri, &amp;error);
+ * if (error)
+ *   {
+ *     g_warning ("Could not find the file: &percnt;s", error-&gt;message);
+ *     g_error_free (error);
+ *   }
+ * else
+ *  {
+ *    /&ast; Use the info object &ast;/
+ *    gtk_recent_info_unref (info);
+ *  }
+ * ]|
+ *
+ * In order to retrieve the list of recently used files, you can use
+ * gtk_recent_manager_get_items(), which returns a list of #GtkRecentInfo
+ * structures.
+ *
+ * A #GtkRecentManager is the model used to populate the contents of
+ * one, or more #GtkRecentChooser implementations.
+ *
+ * <note><para>The maximum age of the recently used files list is
+ * controllable through the #GtkSettings:gtk-recent-files-max-age
+ * property.</para></note>
+ *
+ * Recently used files are supported since GTK+ 2.10.
+ */
+
 #include "config.h"
 
 #include <sys/types.h>
@@ -59,6 +128,17 @@ typedef struct
   time_t stamp;
 } RecentAppInfo;
 
+/**
+ * GtkRecentInfo:
+ *
+ * <structname>GtkRecentInfo</structname> is an opaque data structure
+ * whose members can only be accessed using the provided API.
+ *
+ * <structname>GtkRecentInfo</structname> constains all the meta-data
+ * associated with an entry in the recently used files list.
+ *
+ * Since: 2.10
+ */
 struct _GtkRecentInfo
 {
   gchar *uri;
@@ -84,7 +164,6 @@ struct _GtkRecentInfo
   gint ref_count;
 };
 
-
 struct _GtkRecentManagerPrivate
 {
   gchar *filename;
@@ -235,7 +314,8 @@ gtk_recent_manager_class_init (GtkRecentManagerClass *klass)
    * @recent_manager: the recent manager
    *
    * Emitted when the current recently used resources manager changes its
-   * contents.
+   * contents, either by calling gtk_recent_manager_add_item() or by another
+   * application.
    *
    * Since: 2.10
    */
diff --git a/gtk/gtkrecentmanager.h b/gtk/gtkrecentmanager.h
index 105d0e2..f23b61e 100644
--- a/gtk/gtkrecentmanager.h
+++ b/gtk/gtkrecentmanager.h
@@ -81,14 +81,29 @@ struct _GtkRecentData
   gboolean is_private;
 };
 
+/**
+ * GtkRecentManager:
+ *
+ * <structname>GtkRecentManager</structname> contains only private data
+ * and should be accessed using the provided API.
+ *
+ * Since: 2.10
+ */
 struct _GtkRecentManager
 {
+  /* <private> */
   GObject parent_instance;
 
-  /* <private> */
   GtkRecentManagerPrivate *priv;
 };
 
+/**
+ * GtkRecentManagerClass:
+ *
+ * <structname>GtkRecentManagerClass</structname> contains only private data.
+ *
+ * Since: 2.10
+ */
 struct _GtkRecentManagerClass
 {
   /*< private >*/
@@ -118,8 +133,10 @@ struct _GtkRecentManagerClass
  *   resources file.
  * @GTK_RECENT_MANAGER_ERROR_UNKNOWN: unspecified error.
  *
- * Error codes for GtkRecentManager operations
- **/
+ * Error codes for #GtkRecentManager operations
+ *
+ * Since: 2.10
+ */
 typedef enum
 {
   GTK_RECENT_MANAGER_ERROR_NOT_FOUND,
@@ -131,6 +148,13 @@ typedef enum
   GTK_RECENT_MANAGER_ERROR_UNKNOWN
 } GtkRecentManagerError;
 
+/**
+ * GTK_RECENT_MANAGER_ERROR:
+ *
+ * The #GError domain for #GtkRecentManager errors.
+ *
+ * Since: 2.10
+ */
 #define GTK_RECENT_MANAGER_ERROR	(gtk_recent_manager_error_quark ())
 GQuark 	gtk_recent_manager_error_quark (void);