From d4e514dccd08e7d38eb149ca44ed517e7dec10ec Mon Sep 17 00:00:00 2001 From: Cosimo Cecchi Date: Mon, 4 Aug 2008 12:56:57 +0200 Subject: [PATCH] Keep on documenting objects. --- libmmanager/mm-application-provider.h | 11 +++++++++-- libmmanager/mm-application.h | 10 ++++++++-- libmmanager/mm-attribute-base-manager.h | 9 ++++++++- libmmanager/mm-attribute-manager.h | 10 +++++++++- libmmanager/mm-attribute.h | 9 ++++++++- libmmanager/mm-category-provider.h | 24 ++++++++++++++++++++++++ libmmanager/mm-category.h | 25 ++++++++++++++++++++++--- libmmanager/mm-dbus-application.h | 21 +++++++++++++++++++++ libmmanager/mm-dbus-category.h | 21 +++++++++++++++++++++ libmmanager/mm-filter-param.h | 18 ++++++++++++++++++ libmmanager/mm-filter.h | 20 +++++++++++++++----- libmmanager/mm-hit-collection-provider.h | 23 +++++++++++++++++++++++ libmmanager/mm-hit-collection.h | 14 ++++++++++++++ libmmanager/mm-hit.h | 17 +++++++++++++++++ libmmanager/mm-manager.h | 16 +++++++++++++++- libmmanager/mm-module-manager.h | 15 +++++++++++++++ 16 files changed, 247 insertions(+), 16 deletions(-) diff --git a/libmmanager/mm-application-provider.h b/libmmanager/mm-application-provider.h index dded93b..4b98360 100644 --- a/libmmanager/mm-application-provider.h +++ b/libmmanager/mm-application-provider.h @@ -34,12 +34,19 @@ 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; diff --git a/libmmanager/mm-application.h b/libmmanager/mm-application.h index f635565..0f089a4 100644 --- a/libmmanager/mm-application.h +++ b/libmmanager/mm-application.h @@ -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 @@ -46,6 +46,12 @@ * or DBus facilities. */ +/** + * MMApplication: + * + * Basic type identifying an application object. + */ + typedef struct _MMApplication MMApplication; typedef struct _MMApplicationDetails MMApplicationDetails; typedef struct _MMApplicationClass MMApplicationClass; diff --git a/libmmanager/mm-attribute-base-manager.h b/libmmanager/mm-attribute-base-manager.h index f9a46eb..61c46b7 100644 --- a/libmmanager/mm-attribute-base-manager.h +++ b/libmmanager/mm-attribute-base-manager.h @@ -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 @@ -47,6 +48,12 @@ * #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; diff --git a/libmmanager/mm-attribute-manager.h b/libmmanager/mm-attribute-manager.h index 6a17f56..e4f34d4 100644 --- a/libmmanager/mm-attribute-manager.h +++ b/libmmanager/mm-attribute-manager.h @@ -39,12 +39,20 @@ 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; diff --git a/libmmanager/mm-attribute.h b/libmmanager/mm-attribute.h index 7171508..9e98376 100644 --- a/libmmanager/mm-attribute.h +++ b/libmmanager/mm-attribute.h @@ -25,7 +25,8 @@ #include /** - * 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. @@ -34,6 +35,12 @@ * implementation of the interface) to get the #MMAttribute. */ +/** + * MMAttribute: + * + * An opaque structure identifying an attribute. + */ + typedef struct _MMAttribute MMAttribute; /* public methods */ diff --git a/libmmanager/mm-category-provider.h b/libmmanager/mm-category-provider.h index a9ea5af..d47e985 100644 --- a/libmmanager/mm-category-provider.h +++ b/libmmanager/mm-category-provider.h @@ -33,9 +33,33 @@ #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; diff --git a/libmmanager/mm-category.h b/libmmanager/mm-category.h index fd1e153..22f1a15 100644 --- a/libmmanager/mm-category.h +++ b/libmmanager/mm-category.h @@ -38,6 +38,21 @@ #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); diff --git a/libmmanager/mm-dbus-application.h b/libmmanager/mm-dbus-application.h index 72849cf..128f190 100644 --- a/libmmanager/mm-dbus-application.h +++ b/libmmanager/mm-dbus-application.h @@ -37,7 +37,28 @@ #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; diff --git a/libmmanager/mm-dbus-category.h b/libmmanager/mm-dbus-category.h index f40b425..6665d31 100644 --- a/libmmanager/mm-dbus-category.h +++ b/libmmanager/mm-dbus-category.h @@ -38,7 +38,28 @@ #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 { diff --git a/libmmanager/mm-filter-param.h b/libmmanager/mm-filter-param.h index 5cb6ead..bc720b3 100644 --- a/libmmanager/mm-filter-param.h +++ b/libmmanager/mm-filter-param.h @@ -37,6 +37,24 @@ #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; diff --git a/libmmanager/mm-filter.h b/libmmanager/mm-filter.h index dd5674d..3879cdd 100644 --- a/libmmanager/mm-filter.h +++ b/libmmanager/mm-filter.h @@ -37,6 +37,21 @@ #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); diff --git a/libmmanager/mm-hit-collection-provider.h b/libmmanager/mm-hit-collection-provider.h index ae52292..6e6167e 100644 --- a/libmmanager/mm-hit-collection-provider.h +++ b/libmmanager/mm-hit-collection-provider.h @@ -33,9 +33,32 @@ #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; diff --git a/libmmanager/mm-hit-collection.h b/libmmanager/mm-hit-collection.h index b2891b5..e3d84c3 100644 --- a/libmmanager/mm-hit-collection.h +++ b/libmmanager/mm-hit-collection.h @@ -37,6 +37,20 @@ #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; diff --git a/libmmanager/mm-hit.h b/libmmanager/mm-hit.h index 11a442d..ce039f2 100644 --- a/libmmanager/mm-hit.h +++ b/libmmanager/mm-hit.h @@ -37,6 +37,23 @@ #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; diff --git a/libmmanager/mm-manager.h b/libmmanager/mm-manager.h index c613c49..e909ceb 100644 --- a/libmmanager/mm-manager.h +++ b/libmmanager/mm-manager.h @@ -38,6 +38,21 @@ #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); diff --git a/libmmanager/mm-module-manager.h b/libmmanager/mm-module-manager.h index 055d7f5..6f9850e 100644 --- a/libmmanager/mm-module-manager.h +++ b/libmmanager/mm-module-manager.h @@ -38,6 +38,21 @@ #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; -- 2.11.4.GIT