diff --git a/docs/reference/gtk/tmpl/gtkrecentmanager.sgml b/docs/reference/gtk/tmpl/gtkrecentmanager.sgml
deleted file mode 100644
index 0f5ab0add5..0000000000
--- a/docs/reference/gtk/tmpl/gtkrecentmanager.sgml
+++ /dev/null
@@ -1,464 +0,0 @@
-
-GtkRecentManager
-
-
-Managing Recently Used Files
-
-
-
-#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.
-
-
-
-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 standard recent manager for
-the #GdkScreen so that informations about the recently used
-files is shared with other people using them. In case the
-default screen is being used, 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);
-
-
-
-While looking up a recently used file is as simple as:
-
-
-
-GtkRecentManager *manager;
-GtkRecentInfo *info;
-GError *error = NULL;
-
-manager = gtk_recent_manager_get_default ();
-info = gtk_recent_manager_lookup_item (manager, file_uri, &error);
-if (error)
- {
- g_warning ("Could not find the file: %s", error->message);
- g_error_free (error);
- }
-else
- {
- /* Use the info object */
- gtk_recent_info_unref (info);
- }
-
-
-
-
-Recently used files are supported since GTK+ 2.10.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Acts as a database of information about the list of recently
-used files. Normally, you retrieve the recent manager for a
-particular screen using gtk_recent_manager_get_for_screen()
-and it will contain information about current recent manager
-for that screen.
-
-
-
-
-
-
-
-@recentmanager: the object which received the signal.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Contains informations found when looking up an entry of the
-recently used files list.
-
-
-
-
-
-
-
-
-@display_name:
-@description:
-@mime_type:
-@app_name:
-@app_exec:
-@groups:
-@is_private:
-
-
-
-The #GQuark used for #GtkRecentManagerError errors.
-
-
-
-
-
-
-
-
-
-@GTK_RECENT_MANAGER_ERROR_NOT_FOUND:
-@GTK_RECENT_MANAGER_ERROR_INVALID_URI:
-@GTK_RECENT_MANAGER_ERROR_INVALID_ENCODING:
-@GTK_RECENT_MANAGER_ERROR_NOT_REGISTERED:
-@GTK_RECENT_MANAGER_ERROR_READ:
-@GTK_RECENT_MANAGER_ERROR_WRITE:
-@GTK_RECENT_MANAGER_ERROR_UNKNOWN:
-
-
-
-
-
-
-@void:
-@Returns:
-
-
-
-
-
-
-
-@void:
-@Returns:
-
-
-
-
-
-
-
-@manager:
-@uri:
-@Returns:
-
-
-
-
-
-
-
-@manager:
-@uri:
-@recent_data:
-@Returns:
-
-
-
-
-
-
-
-@manager:
-@uri:
-@error:
-@Returns:
-
-
-
-
-
-
-
-@manager:
-@uri:
-@error:
-@Returns:
-
-
-
-
-
-
-
-@manager:
-@uri:
-@Returns:
-
-
-
-
-
-
-
-@manager:
-@uri:
-@new_uri:
-@error:
-@Returns:
-
-
-
-
-
-
-
-@manager:
-@Returns:
-
-
-
-
-
-
-
-@manager:
-@error:
-@Returns:
-
-
-
-
-
-
-
-@info:
-@Returns:
-
-
-
-
-
-
-
-@info:
-
-
-
-
-
-
-
-@info:
-@Returns:
-
-
-
-
-
-
-
-@info:
-@Returns:
-
-
-
-
-
-
-
-@info:
-@Returns:
-
-
-
-
-
-
-
-@info:
-@Returns:
-
-
-
-
-
-
-
-@info:
-@Returns:
-
-
-
-
-
-
-
-@info:
-@Returns:
-
-
-
-
-
-
-
-@info:
-@Returns:
-
-
-
-
-
-
-
-@info:
-@Returns:
-
-
-
-
-
-
-
-@info:
-@app_name:
-@app_exec:
-@count:
-@time_:
-@Returns:
-
-
-
-
-
-
-
-@info:
-@length:
-@Returns:
-
-
-
-
-
-
-
-@info:
-@Returns:
-
-
-
-
-
-
-
-@info:
-@length:
-@Returns:
-
-
-
-
-
-
-
-@info:
-@group_name:
-@Returns:
-
-
-
-
-
-
-
-@info:
-@app_name:
-@Returns:
-
-
-
-
-
-
-
-@info:
-@size:
-@Returns:
-
-
-
-
-
-
-
-@info:
-@Returns:
-
-
-
-
-
-
-
-@info:
-@Returns:
-
-
-
-
-
-
-
-@info:
-@Returns:
-
-
-
-
-
-
-
-@info:
-@Returns:
-
-
-
-
-
-
-
-@info:
-@Returns:
-
-
-
-
-
-
-
-@info_a:
-@info_b:
-@Returns:
-
-
diff --git a/gtk/gtkrecentmanager.c b/gtk/gtkrecentmanager.c
index 58b41dca79..4226de2997 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.
+ *
+ * The recently used files list is per user.
+ *
+ * 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, &error);
+ * if (error)
+ * {
+ * g_warning ("Could not find the file: %s", error->message);
+ * g_error_free (error);
+ * }
+ * else
+ * {
+ * /* Use the info object */
+ * 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.
+ *
+ * The maximum age of the recently used files list is
+ * controllable through the #GtkSettings:gtk-recent-files-max-age
+ * property.
+ *
+ * Recently used files are supported since GTK+ 2.10.
+ */
+
#include "config.h"
#include
@@ -59,6 +128,17 @@ typedef struct
time_t stamp;
} RecentAppInfo;
+/**
+ * GtkRecentInfo:
+ *
+ * GtkRecentInfo is an opaque data structure
+ * whose members can only be accessed using the provided API.
+ *
+ * GtkRecentInfo 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 105d0e2fe7..f23b61e364 100644
--- a/gtk/gtkrecentmanager.h
+++ b/gtk/gtkrecentmanager.h
@@ -81,14 +81,29 @@ struct _GtkRecentData
gboolean is_private;
};
+/**
+ * GtkRecentManager:
+ *
+ * GtkRecentManager contains only private data
+ * and should be accessed using the provided API.
+ *
+ * Since: 2.10
+ */
struct _GtkRecentManager
{
+ /* */
GObject parent_instance;
- /* */
GtkRecentManagerPrivate *priv;
};
+/**
+ * GtkRecentManagerClass:
+ *
+ * GtkRecentManagerClass 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);