From aa27c27ccdecc9d1c7d8c526e99eb86ec787e2de Mon Sep 17 00:00:00 2001
From: Cosimo Cecchi <cosimoc@gnome.org>
Date: Sat, 2 Aug 2008 09:58:57 +0200
Subject: [PATCH] Keep on documenting methods.

---
 src/mm-attribute.c | 58 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 src/mm-category.c  | 52 ++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 110 insertions(+)

diff --git a/src/mm-attribute.c b/src/mm-attribute.c
index b3a6cb6..4816834 100644
--- a/src/mm-attribute.c
+++ b/src/mm-attribute.c
@@ -31,30 +31,73 @@ struct _MMAttribute {
 
 /* public methods */
 
+/**
+ * mm_attribute_get_name:
+ * @a: a #MMAttribute.
+ *
+ * Gets the name of @a.
+ *
+ * Return value: a string containing the name of @a.
+ */
+
 const char *
 mm_attribute_get_name (MMAttribute *a)
 {
   return a->name;
 }
 
+/**
+ * mm_attribute_get_description:
+ * @a: a #MMAttribute.
+ *
+ * Gets a textual description of @a.
+ *
+ * Return value: a string containing a description of @a.
+ */
+
 const char *
 mm_attribute_get_description (MMAttribute *a)
 {
   return a->description;
 }
 
+/**
+ * mm_attribute_get_value_type:
+ * @a: a #MMAttribute.
+ *
+ * Gets the #GType that a possible value for @a should have.
+ *
+ * Return value: a #GType.
+ */
+
 GType
 mm_attribute_get_value_type (MMAttribute *a)
 {
   return a->type;
 }
 
+/**
+ * mm_attribute_get_id:
+ * @a: a #MMAttribute.
+ *
+ * Gets the unique identifier of @a.
+ *
+ * Return value: a string containing the unique identifier of @a.
+ */
+
 const char *
 mm_attribute_get_id (MMAttribute *a)
 {
   return a->id;
 }
 
+/**
+ * mm_attribute_free:
+ * @a: a #MMAttribute.
+ *
+ * Release the memory occupied by a #MMAttribute.
+ */
+
 void
 mm_attribute_free (MMAttribute *a)
 {
@@ -65,6 +108,21 @@ mm_attribute_free (MMAttribute *a)
   g_slice_free (MMAttribute, a);
 }
 
+/**
+ * mm_attribute_new:
+ * @type: the #GType that a possible value for this attribute should have.
+ * @id: a string containing an unique id for the attribute.
+ * @name: a string containing the attribute's name.
+ * @description: a string containing the attribute's description.
+ *
+ * Builds a new #MMAttribute structure, with the specified properties. This is
+ * useful only if you're implementing a #MMAttributeManager, as the attributes
+ * are supposed to be static and owned by the manager.
+ *
+ * Return value: a newly allocated #MMAttribute structure. Free it with
+ * #mm_attribute_free.
+ */
+
 MMAttribute *
 mm_attribute_new (GType type,
                   const char *id,
diff --git a/src/mm-category.c b/src/mm-category.c
index fb64289..113005b 100644
--- a/src/mm-category.c
+++ b/src/mm-category.c
@@ -74,6 +74,18 @@ mm_category_init (MMCategory *c)
 }
 
 /* public methods */
+
+/**
+ * mm_category_set_attributes:
+ * @category: a #MMCategory.
+ * @app: a #MMApplication.
+ * @name: a string containing the name for the category.
+ * @icon: a #GIcon containing the icon for the category.
+ *
+ * Sets all the specified properties and attributes to @category. This is useful
+ * only for #MMCategory implementations.
+ */
+
 void
 mm_category_set_attributes (MMCategory *category,
                             MMApplication *app,
@@ -89,6 +101,16 @@ mm_category_set_attributes (MMCategory *category,
   }
 }
 
+/**
+ * mm_category_get_icon:
+ * @c: a #MMCategory.
+ *
+ * Gets the category's icon.
+ *
+ * Return value: a #GIcon containing the icon of the category or %NULL. Unref it
+ * when done.
+ */
+
 GIcon *
 mm_category_get_icon (MMCategory *c)
 {
@@ -98,6 +120,15 @@ mm_category_get_icon (MMCategory *c)
   return c->details->icon ? g_object_ref (c->details->icon) : NULL;
 }
 
+/**
+ * mm_category_get_name:
+ * @c: a #MMCategory.
+ *
+ * Gets the name of the category.
+ *
+ * Return value: a string containing the name of the category.
+ */
+
 const char *
 mm_category_get_name (MMCategory *c)
 {
@@ -107,6 +138,18 @@ mm_category_get_name (MMCategory *c)
   return c->details->name;
 }
 
+/**
+ * mm_collection_get_hits:
+ * @c: a #MMCategory.
+ * @f: a #MMFilter.
+ * @err: a #GError.
+ *
+ * Gets a #MMHitCollection of all the hits contained in @c and satisfying the
+ * requirements of @f.
+ *
+ * Return value: a #MMHitCollection or %NULL (in this case, the #GError is set).
+ */
+
 MMHitCollection *
 mm_category_get_hits (MMCategory *c,
                       MMFilter *f,
@@ -122,6 +165,15 @@ mm_category_get_hits (MMCategory *c,
     NULL : ((* MM_CATEGORY_CLASS (G_OBJECT_GET_CLASS (c))->get_hits) (c, f, err));
 }
 
+/**
+ * mm_category_get_application:
+ * @c: a #MMCategory.
+ *
+ * Gets the #MMApplication to which @c belong.
+ *
+ * Return value: a #MMApplication. Unref it when done.
+ */
+
 MMApplication *
 mm_category_get_application (MMCategory *c)
 {
-- 
2.11.4.GIT