Keep on documenting objects.
authorCosimo Cecchi <cosimoc@gnome.org>
Mon, 4 Aug 2008 10:56:57 +0000 (4 12:56 +0200)
committerCosimo Cecchi <cosimoc@gnome.org>
Mon, 4 Aug 2008 10:56:57 +0000 (4 12:56 +0200)
16 files changed:
libmmanager/mm-application-provider.h
libmmanager/mm-application.h
libmmanager/mm-attribute-base-manager.h
libmmanager/mm-attribute-manager.h
libmmanager/mm-attribute.h
libmmanager/mm-category-provider.h
libmmanager/mm-category.h
libmmanager/mm-dbus-application.h
libmmanager/mm-dbus-category.h
libmmanager/mm-filter-param.h
libmmanager/mm-filter.h
libmmanager/mm-hit-collection-provider.h
libmmanager/mm-hit-collection.h
libmmanager/mm-hit.h
libmmanager/mm-manager.h
libmmanager/mm-module-manager.h

index dded93b..4b98360 100644 (file)
                                                 MM_TYPE_APPLICATION_PROVIDER, MMApplicationProviderIface))
 
 /**
- * MMApplicationProvider:
- *
+ * SECTION:mm-application-provider
+ * @short_description: provides #MMApplication objects.
+ * 
  * A handle to an object implementing the #MMApplicationProviderIface iterface.
  * You need this to build a #MMApplication object if you're using #MMModule.
  */
 
+/**
+ * MMApplicationProvider:
+ *
+ * An abstract type that specifies an application provider.
+ */
+
 typedef struct _MMApplicationProvider MMApplicationProvider;
 typedef struct _MMApplicationProviderIface MMApplicationProviderIface;
 
index f635565..0f089a4 100644 (file)
@@ -36,9 +36,9 @@
                                         MM_TYPE_APPLICATION))
 #define MM_APPLICATION_GET_CLASS(obj)  (G_TYPE_INSTANCE_GET_CLASS((obj),\
                                         MM_TYPE_APPLICATION, MMApplicationClass))
-
 /**
- * MMApplication:
+ * SECTION:mm-application
+ * @short_description: an application object.
  *
  * An object which identifies an application inside the library. This object
  * has two implementations: #MMSoApplication and #MMDBusApplication, which
  * or DBus facilities.
  */
 
+/**
+ * MMApplication:
+ *
+ * Basic type identifying an application object.
+ */
+
 typedef struct _MMApplication        MMApplication;
 typedef struct _MMApplicationDetails MMApplicationDetails;
 typedef struct _MMApplicationClass   MMApplicationClass;
index f9a46eb..61c46b7 100644 (file)
@@ -39,7 +39,8 @@
                                                    MM_TYPE_ATTRIBUTE_BASE_MANAGER, MMAttributeBaseManagerClass))
 
 /**
- * MMAttributeBaseManager:
+ * SECTION:mm-attribute-base-manager
+ * @short_description: manager implementation for base attributes.
  *
  * Implementation of a #MMAttributeManager for basic attributes. Currently the
  * only supported attributes are "uri" and "name", but this could be easily
  * #MMAttributeBaseManager have the prefix "base" in their id.
  */
 
+/**
+ * MMAttributeBaseManager:
+ *
+ * An implementation of the #MMAttributeMangaer interface for basic attributes.
+ */
+
 typedef struct _MMAttributeBaseManager MMAttributeBaseManager;
 typedef struct _MMAttributeBaseManagerClass MMAttributeBaseManagerClass;
 
index 6a17f56..e4f34d4 100644 (file)
                                               MM_TYPE_ATTRIBUTE_MANAGER, MMAttributeManagerIface))
 
 /**
- * MMAttributeManager:
+ * SECTION:mm-attribute-manager
+ * @short_description: attribute manager.
  *
  * An object implementing the #MMAttributeManagerIface interface. It manages and
  * owns a number of attributes, offering the chance to look them up by their
  * unique id.
  */
+
+/**
+ * MMAttributeManager:
+ *
+ * Abstract type for attribute managers.
+ */
 
 typedef struct _MMAttributeManager      MMAttributeManager;
 typedef struct _MMAttributeManagerIface MMAttributeManagerIface;
index 7171508..9e98376 100644 (file)
@@ -25,7 +25,8 @@
 #include <glib-object.h>
 
 /**
- * MMAttribute:
+ * SECTION:mm-attribute
+ * @short_description: an attribute.
  *
  * Structure defining an attribute which the #MMCollection can be queried on.
  * This structure is used both to build #MMFilterParam and #MMHit objects.
  * implementation of the interface) to get the #MMAttribute.
  */
 
+/**
+ * MMAttribute:
+ *
+ * An opaque structure identifying an attribute.
+ */
+
 typedef struct _MMAttribute      MMAttribute;
 
 /* public methods */
index a9ea5af..d47e985 100644 (file)
 #define MM_CATEGORY_PROVIDER_GET_IFACE(obj) (G_TYPE_INSTANCE_GET_INTERFACE ((obj),\
                                              MM_TYPE_CATEGORY_PROVIDER, MMCategoryProviderIface))
 
+/**
+ * SECTION:mm-category-provider
+ * @short_description: provides #MMCategory objects.
+ *
+ * A handle to an object implementing the #MMCategoryProviderIface iterface.
+ * You need this to get a list of #MMCategory objects for a #MMSoApplication,
+ * i.e. if you're using #MMModule.
+ */
+
+/**
+ * MMCategoryProvider:
+ *
+ * An abstract type that provides categories.
+ */
+
 typedef struct _MMCategoryProvider      MMCategoryProvider;
 typedef struct _MMCategoryProviderIface MMCategoryProviderIface;
 
+/**
+ * MMCategoryProviderIface:
+ * @interface: the parent interface.
+ * @get_categories: Gets a #GList of #MMCategory objects provided by the 
+ * application.
+ *
+ * Interface to build #MMCategory objects with #MMModule.
+ */
+
 struct _MMCategoryProviderIface {
   GTypeInterface interface;
 
index fd1e153..22f1a15 100644 (file)
 #define MM_CATEGORY_GET_CLASS(obj)  (G_TYPE_INSTANCE_GET_CLASS((obj),\
                                      MM_TYPE_CATEGORY, MMCategoryClass))
 
+/**
+ * SECTION:mm-category
+ * @short_description: a category of a library.
+ *
+ * A category of an application's library. This could be e.g. "Last Roll"
+ * for a photo application, a playlist for a video or music application or
+ * something like "Podcasts". Each category has a name and an icon.
+ */
+
+/**
+ * MMCategory:
+ *
+ * A basic type for a category object.
+ */
+
 typedef struct _MMCategory        MMCategory;
 typedef struct _MMCategoryDetails MMCategoryDetails;
 typedef struct _MMCategoryClass   MMCategoryClass;
@@ -47,6 +62,13 @@ struct _MMCategory {
   MMCategoryDetails *details;
 };
 
+/**
+ * MMCategoryClass:
+ * @get_hits: Gets a #MMHitCollection for the specified filter.
+ *
+ * Class of a #MMCategory object.
+ */
+
 struct _MMCategoryClass {
   GObjectClass parent_class;
 
@@ -61,12 +83,9 @@ void              mm_category_set_attributes  (MMCategory    *category,
                                                MMApplication *app,
                                                const char    *name,
                                                GIcon         *icon);
-/* return the icon of the category */
 GIcon*            mm_category_get_icon        (MMCategory    *category);
-/* return the name of the category */
 const char*       mm_category_get_name        (MMCategory    *category);
 MMApplication *   mm_category_get_application (MMCategory    *category);
-/* return a collection of hits inside the category for the given filter */
 MMHitCollection*  mm_category_get_hits        (MMCategory    *category,
                                                MMFilter      *filter,
                                                GError       **error);
index 72849cf..128f190 100644 (file)
 #define MM_DBUS_APPLICATION_GET_CLASS(obj)  (G_TYPE_INSTANCE_GET_CLASS((obj),\
                                              MM_TYPE_DBUS_APPLICATION, MMDBusApplicationClass))
 
+/**
+ * SECTION:mm-dbus-application
+ * @short_description: DBus implementation of #MMApplication.
+ *
+ * A #MMDBusApplication is an implementation of #MMApplication for applications
+ * using the DBus interface of the library.
+ */
+/**
+ * MMDBusApplication:
+ *
+ * A DBus implementation of a #MMApplication.
+ */
+
 typedef struct _MMDBusApplication MMDBusApplication;
+
+/**
+ * MMDBusApplicationClass:
+ *
+ * Class of #MMDBusApplication objects.
+ */
+
 typedef struct _MMDBusApplicationClass MMDBusApplicationClass;
 typedef struct _MMDBusApplicationDetails MMDBusApplicationDetails;
 
index f40b425..6665d31 100644 (file)
 #define MM_DBUS_CATEGORY_GET_CLASS(obj)  (G_TYPE_INSTANCE_GET_CLASS((obj),\
                                           MM_TYPE_DBUS_CATEGORY, MMDBusCategoryClass))
 
+/**
+ * SECTION:mm-dbus-category
+ * @short_description: DBus implementation of #MMCategory.
+ *
+ * A #MMDBusCategory is an implementation of #MMCategory for categories
+ * using the DBus interface of the library.
+ */
+
+/**
+ * MMDBusCategory:
+ *
+ * A DBus implementation of a #MMCategory.
+ */
+
 typedef struct _MMDBusCategory      MMDBusCategory;
+
+/**
+ * MMDBusCategoryClass:
+ *
+ * Class of #MMDBusCategory objects.
+ */
+
 typedef struct _MMDBusCategoryClass MMDBusCategoryClass;
 
 struct _MMDBusCategory {
index 5cb6ead..bc720b3 100644 (file)
 #define MM_FILTER_PARAM_GET_CLASS(obj)  (G_TYPE_INSTANCE_GET_CLASS((obj),\
                                          MM_TYPE_FILTER_PARAM, MMFilterParamClass))
 
+/**
+ * SECTION:mm-filter-param
+ * @short_description: parameter for a #MMFilter.
+ *
+ * #MMFilterParam is an object identifying a parameter for a #MMFilter.
+ * Thus to make a query, you have to build #MMFilterParam objects and add them
+ * to a #MMFilter. To create a #MMFilterParam object, you should provide a
+ * #MMAttribute, a #GValue and a #MMComparisionOperator which specifies the
+ * relation between them. #MMFilterParam objects are reusable, i.e. you can add
+ * the same #MMFilterParam to more than a filter.
+ */
+
+/**
+ * MMFilterParam:
+ *
+ * A parameter for a #MMFilter.
+ */
+
 typedef struct _MMFilterParam        MMFilterParam;
 typedef struct _MMFilterParamDetails MMFilterParamDetails;
 typedef struct _MMFilterParamClass   MMFilterParamClass;
index dd5674d..3879cdd 100644 (file)
 #define MM_FILTER_GET_CLASS(obj)  (G_TYPE_INSTANCE_GET_CLASS((obj),\
                                    MM_TYPE_FILTER, MMFilterClass))
 
+/**
+ * SECTION:mm-filter
+ * @short_description: a filter.
+ *
+ * #MMFilter is an object representing a query. It is no more than a collection
+ * of #MMFilterParam objects. You must pass a #MMFilter object to a #MMCategory
+ * to get a #MMHitCollection.
+ */
+
+/**
+ * MMFilter:
+ *
+ * A filter, i.e. an object representing a query.
+ */
+
 typedef struct _MMFilter        MMFilter;
 typedef struct _MMFilterDetails MMFilterDetails;
 typedef struct _MMFilterClass   MMFilterClass;
@@ -52,16 +67,11 @@ struct _MMFilterClass {
 
 /* public methods */
 GType      mm_filter_get_type             (void);
-
-/* adds a filtering parameter to the filter */
 void       mm_filter_add_filtering_param  (MMFilter        *filter,
                                            MMFilterParam   *fp);
-/* adds more than one filtering param to the filter */
 void       mm_filter_add_filtering_params (MMFilter        *filter,
                                            GList           *fps);
-/* clears all the filtering params set on the filter */
 void       mm_filter_clear                (MMFilter        *filter);
-/* gets all the filtering params set on the filter */
 GList *    mm_filter_get_filtering_params (MMFilter        *filter);
 
 MMFilter * mm_filter_new                  (void);
index ae52292..6e6167e 100644 (file)
 #define MM_HIT_COLLECTION_PROVIDER_GET_IFACE(obj) (G_TYPE_INSTANCE_GET_INTERFACE ((obj),\
                                                    MM_TYPE_HIT_COLLECTION_PROVIDER, MMHitCollectionProviderIface))
 
+/**
+ * SECTION:mm-hit-collection-provider
+ * @short_description: provides #MMHitCollection objects.
+ *
+ * A handle to an object implementing the #MMHitCollectionProvider iterface.
+ * You need this to get a #MMHitCollection for a #MMSoCategory,
+ * i.e. if you're using #MMModule.
+ */
+
+/**
+ * MMHitCollectionProvider:
+ *
+ * An abstract type that provides hit collections.
+ */
+
 typedef struct _MMHitCollectionProvider      MMHitCollectionProvider;
 typedef struct _MMHitCollectionProviderIface MMHitCollectionProviderIface;
 
+/**
+ * MMHitCollectionProviderIface:
+ * @interface: the parent interface.
+ * @get_hits: Gets a #MMHitCollection for the specified category and filter.
+ *
+ * Interface to build #MMHitCollection objects with #MMModule.
+ */
+
 struct _MMHitCollectionProviderIface {
   GTypeInterface interface;
 
index b2891b5..e3d84c3 100644 (file)
 #define MM_HIT_COLLECTION_GET_CLASS(obj)  (G_TYPE_INSTANCE_GET_CLASS((obj),\
                                            MM_TYPE_HIT_COLLECTION, MMHitCollectionClass))
 
+/**
+ * SECTION:mm-hit-collection
+ * @short_description: a collection of #MMHit objects.
+ *
+ * #MMHitCollection is a simple collection of #MMHit objects, and encapsulates
+ * the results of a query.
+ */
+/**
+ * MMHitCollection:
+ *
+ * An object identifying a collection of #MMHit objects.
+ */
+
 typedef struct _MMHitCollection        MMHitCollection;
 typedef struct _MMHitCollectionDetails MMHitCollectionDetails;
 typedef struct _MMHitCollectionClass   MMHitCollectionClass;
index 11a442d..ce039f2 100644 (file)
 #define MM_HIT_GET_CLASS(obj)  (G_TYPE_INSTANCE_GET_CLASS((obj),\
                                 MM_TYPE_HIT, MMHitClass))
 
+/**
+ * SECTION:mm-hit
+ * @short_description: a hit (i.e. a result of a query).
+ *
+ * #MMHit is a single result of a query. It's worth to note that #MMHit objects
+ * are created by the application, so they could have some blank attribute, if
+ * the application doesn't support it. More generally, a #MMHit should have all
+ * the basic attributes and all those supported by its media type set, but it's 
+ * up to the applications to fill them in.
+ */
+/**
+ * MMHit:
+ *
+ * An object identifying a single result of a query.
+ */
+
 typedef struct _MMHit        MMHit;
 typedef struct _MMHitDetails MMHitDetails;
 typedef struct _MMHitClass   MMHitClass;
index c613c49..e909ceb 100644 (file)
 #define MM_MANAGER_GET_CLASS(obj)  (G_TYPE_INSTANCE_GET_CLASS((obj),\
                                     MM_TYPE_MANAGER, MMManagerClass))
 
+/**
+ * SECTION:mm-manager
+ * @short_description: manager of the library.
+ *
+ * The #MMManager keeps track of all the registered applications, and offers
+ * some methods to access them. The object is a singleton, owned by the
+ * library.
+ */
+/**
+ * MMManager:
+ *
+ * Base manager for the library.
+ */
+
 typedef struct _MMManager        MMManager;
 typedef struct _MMManagerDetails MMManagerDetails;
 typedef struct _MMManagerClass   MMManagerClass;
@@ -55,7 +70,6 @@ struct _MMManagerClass {
 MMManager* mm_manager_get                  (void);
 GType      mm_manager_get_type             (void);
 
-/* return a list of the registered applications for the specified types */
 GList*    mm_manager_get_application_list_for_type            (MMManager        *manager,
                                                                 MMApplicationType type);
 GList*     mm_manager_get_application_list                     (MMManager        *manager);
index 055d7f5..6f9850e 100644 (file)
 #define MM_IS_MODULE_MANAGER_CLASS(klass) (G_TYPE_CLASS_CHECK_CLASS_TYPE ((klass),\
                                            MM_TYPE_MODULE_MANAGER))
 
+/**
+ * SECTION:mm-module-manager
+ * @short_description: module manager.
+ *
+ * #MMModuleManager manages all the #MMModule objects registered in the library,
+ * e.g. all the applications registered with .so files. You shouldn't need to
+ * access this object directly. The object is a singleton owned by #MMManager.
+ */
+
+/**
+ * MMModuleManager:
+ *
+ * Manager for #MMModule objects.
+ */
+
 typedef struct _MMModuleManager        MMModuleManager;
 typedef struct _MMModuleManagerDetails MMModuleManagerDetails;
 typedef struct _MMModuleManagerClass   MMModuleManagerClass;