GNOME.org
 

[gnome-software] Add gtk-doc markup for GsReview

commit a0e91016d1732a3e7e01edcee4315a8b2639b853
Author: Richard Hughes <richard hughsie com>
Date:   Tue May 10 08:00:46 2016 +0100

    Add gtk-doc markup for GsReview

 src/gs-review.c |  151 ++++++++++++++++++++++++++++++++++++++++++++++++-------
 src/gs-review.h |   30 ++++++++++--
 2 files changed, 158 insertions(+), 23 deletions(-)
---
diff --git a/src/gs-review.c b/src/gs-review.c
index f4d4323..3e1a438 100644
--- a/src/gs-review.c
+++ b/src/gs-review.c
@@ -19,6 +19,13 @@
  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  */
 
+/**
+ * SECTION:gs-review
+ * @short_description: An application user review
+ *
+ * This object represents a user-submitted application review.
+ */
+
 #include "config.h"
 
 #include "gs-review.h"
@@ -56,6 +63,12 @@ G_DEFINE_TYPE (GsReview, gs_review, G_TYPE_OBJECT)
 
 /**
  * gs_review_get_karma:
+ * @review: a #GsReview
+ *
+ * Gets the karma for the review, where positive numbers indicate
+ * more positive feedback for the review.
+ *
+ * Returns: the karma value, or 0 for unset.
  */
 gint
 gs_review_get_karma (GsReview *review)
@@ -66,6 +79,13 @@ gs_review_get_karma (GsReview *review)
 
 /**
  * gs_review_set_karma:
+ * @review: a #GsReview
+ * @karma: a karma value
+ *
+ * Sets the karma for the review, where positive numbers indicate
+ * more positive feedback for the review.
+ *
+ * Karma can be positive or negative, or 0 for unset.
  */
 void
 gs_review_set_karma (GsReview *review, gint karma)
@@ -76,9 +96,12 @@ gs_review_set_karma (GsReview *review, gint karma)
 
 /**
  * gs_review_get_score:
+ * @review: a #GsReview
  *
  * This allows the UI to sort reviews into the correct order.
  * Higher numbers indicate a more important or relevant review.
+ *
+ * Returns: the review score, or 0 for unset.
  */
 gint
 gs_review_get_score (GsReview *review)
@@ -89,6 +112,11 @@ gs_review_get_score (GsReview *review)
 
 /**
  * gs_review_set_score:
+ * @review: a #GsReview
+ * @score: a score value
+ *
+ * Sets the score for the review, where positive numbers indicate
+ * a better review for the specific user.
  */
 void
 gs_review_set_score (GsReview *review, gint score)
@@ -99,6 +127,11 @@ gs_review_set_score (GsReview *review, gint score)
 
 /**
  * gs_review_get_summary:
+ * @review: a #GsReview
+ *
+ * Gets the review summary.
+ *
+ * Returns: the one-line summary, e.g. "Awesome application"
  */
 const gchar *
 gs_review_get_summary (GsReview *review)
@@ -109,6 +142,10 @@ gs_review_get_summary (GsReview *review)
 
 /**
  * gs_review_set_summary:
+ * @review: a #GsReview
+ * @summary: a one-line summary, e.g. "Awesome application"
+ *
+ * Sets the one-line summary that may be displayed in bold.
  */
 void
 gs_review_set_summary (GsReview *review, const gchar *summary)
@@ -120,6 +157,11 @@ gs_review_set_summary (GsReview *review, const gchar *summary)
 
 /**
  * gs_review_get_text:
+ * @review: a #GsReview
+ *
+ * Gets the multi-line review text that forms the body of the review.
+ *
+ * Returns: the string, or %NULL
  **/
 const gchar *
 gs_review_get_text (GsReview *review)
@@ -130,6 +172,10 @@ gs_review_get_text (GsReview *review)
 
 /**
  * gs_review_set_text:
+ * @review: a #GsReview
+ * @text: multi-line text
+ *
+ * Sets the multi-line review text that forms the body of the review.
  */
 void
 gs_review_set_text (GsReview *review, const gchar *text)
@@ -141,6 +187,11 @@ gs_review_set_text (GsReview *review, const gchar *text)
 
 /**
  * gs_review_get_rating:
+ * @review: a #GsReview
+ *
+ * Gets the star rating of the review, where 100 is 5 stars.
+ *
+ * Returns: integer as a percentage, or -1 for unset
  */
 gint
 gs_review_get_rating (GsReview *review)
@@ -151,6 +202,10 @@ gs_review_get_rating (GsReview *review)
 
 /**
  * gs_review_set_rating:
+ * @review: a #GsReview
+ * @rating: a integer as a percentage, or -1 for unset
+ *
+ * Sets the star rating of the review, where 100 is 5 stars..
  */
 void
 gs_review_set_rating (GsReview *review, gint rating)
@@ -161,6 +216,12 @@ gs_review_set_rating (GsReview *review, gint rating)
 
 /**
  * gs_review_get_flags:
+ * @review: a #GsReview
+ *
+ * Gets any flags set on the review, for example if the user has already
+ * voted on the review or if the user wrote the review themselves.
+ *
+ * Returns: a #GsReviewFlags, e.g. %GS_REVIEW_FLAG_SELF
  */
 GsReviewFlags
 gs_review_get_flags (GsReview *review)
@@ -171,6 +232,11 @@ gs_review_get_flags (GsReview *review)
 
 /**
  * gs_review_set_flags:
+ * @review: a #GsReview
+ * @flags: a #GsReviewFlags, e.g. %GS_REVIEW_FLAG_SELF
+ *
+ * Gets any flags set on the review, for example if the user has already
+ * voted on the review or if the user wrote the review themselves.
  */
 void
 gs_review_set_flags (GsReview *review, GsReviewFlags flags)
@@ -181,6 +247,10 @@ gs_review_set_flags (GsReview *review, GsReviewFlags flags)
 
 /**
  * gs_review_add_flags:
+ * @review: a #GsReview
+ * @flags: a #GsReviewFlags, e.g. %GS_REVIEW_FLAG_SELF
+ *
+ * Adds flags to an existing review without replacing the other flags.
  */
 void
 gs_review_add_flags (GsReview *review, GsReviewFlags flags)
@@ -191,6 +261,11 @@ gs_review_add_flags (GsReview *review, GsReviewFlags flags)
 
 /**
  * gs_review_get_reviewer:
+ * @review: a #GsReview
+ *
+ * Gets the name of the reviewer.
+ *
+ * Returns: the reviewer name, e.g. "David Smith", or %NULL
  **/
 const gchar *
 gs_review_get_reviewer (GsReview *review)
@@ -200,7 +275,26 @@ gs_review_get_reviewer (GsReview *review)
 }
 
 /**
+ * gs_review_set_reviewer:
+ * @review: a #GsReview
+ * @reviewer: the reviewer name, e.g. "David Smith"
+ *
+ * Sets the name of the reviewer, which can be left unset.
+ */
+void
+gs_review_set_reviewer (GsReview *review, const gchar *reviewer)
+{
+       g_return_if_fail (GS_IS_REVIEW (review));
+       g_free (review->reviewer);
+       review->reviewer = g_strdup (reviewer);
+}
+
+/**
  * gs_review_set_version:
+ * @review: a #GsReview
+ * @version: a version string, e.g. "0.1.2"
+ *
+ * Sets the version string for the application being reviewed.
  */
 void
 gs_review_set_version (GsReview *review, const gchar *version)
@@ -212,6 +306,11 @@ gs_review_set_version (GsReview *review, const gchar *version)
 
 /**
  * gs_review_get_version:
+ * @review: a #GsReview
+ *
+ * Gets the version string for the application being reviewed..
+ *
+ * Returns: the version string, e.g. "0.1.2", or %NULL for unset
  **/
 const gchar *
 gs_review_get_version (GsReview *review)
@@ -221,18 +320,12 @@ gs_review_get_version (GsReview *review)
 }
 
 /**
- * gs_review_set_reviewer:
- */
-void
-gs_review_set_reviewer (GsReview *review, const gchar *reviewer)
-{
-       g_return_if_fail (GS_IS_REVIEW (review));
-       g_free (review->reviewer);
-       review->reviewer = g_strdup (reviewer);
-}
-
-/**
  * gs_review_get_date:
+ * @review: a #GsReview
+ *
+ * Gets the date the review was originally submitted.
+ *
+ * Returns: the #GDateTime, or %NULL for unset
  **/
 GDateTime *
 gs_review_get_date (GsReview *review)
@@ -243,6 +336,10 @@ gs_review_get_date (GsReview *review)
 
 /**
  * gs_review_set_date:
+ * @review: a #GsReview
+ * @date: a #GDateTime, or %NULL
+ *
+ * Sets the date the review was originally submitted.
  */
 void
 gs_review_set_date (GsReview *review, GDateTime *date)
@@ -255,16 +352,32 @@ gs_review_set_date (GsReview *review, GDateTime *date)
 
 /**
  * gs_review_get_metadata_item:
+ * @review: a #GsReview
+ * @key: a string
+ *
+ * Gets some metadata from a review object.
+ * It is left for the the plugin to use this method as required, but a
+ * typical use would be to retrieve some secure authentication token.
+ *
+ * Returns: A string value, or %NULL for not found
  */
 const gchar *
 gs_review_get_metadata_item (GsReview *review, const gchar *key)
 {
        g_return_val_if_fail (GS_IS_REVIEW (review), NULL);
+       g_return_val_if_fail (key != NULL, NULL);
        return g_hash_table_lookup (review->metadata, key);
 }
 
 /**
  * gs_review_add_metadata:
+ * @review: a #GsReview
+ * @key: a string
+ * @value: a string
+ *
+ * Adds metadata to the review object.
+ * It is left for the the plugin to use this method as required, but a
+ * typical use would be to store some secure authentication token.
  */
 void
 gs_review_add_metadata (GsReview *review, const gchar *key, const gchar *value)
@@ -381,7 +494,7 @@ gs_review_class_init (GsReviewClass *klass)
        object_class->set_property = gs_review_set_property;
 
        /**
-        * GsApp:karma:
+        * GsReview:karma:
         */
        pspec = g_param_spec_int ("karma", NULL, NULL,
                                  G_MININT, G_MAXINT, 0,
@@ -389,7 +502,7 @@ gs_review_class_init (GsReviewClass *klass)
        g_object_class_install_property (object_class, PROP_KARMA, pspec);
 
        /**
-        * GsApp:summary:
+        * GsReview:summary:
         */
        pspec = g_param_spec_string ("summary", NULL, NULL,
                                     NULL,
@@ -397,7 +510,7 @@ gs_review_class_init (GsReviewClass *klass)
        g_object_class_install_property (object_class, PROP_SUMMARY, pspec);
 
        /**
-        * GsApp:text:
+        * GsReview:text:
         */
        pspec = g_param_spec_string ("text", NULL, NULL,
                                     NULL,
@@ -405,7 +518,7 @@ gs_review_class_init (GsReviewClass *klass)
        g_object_class_install_property (object_class, PROP_TEXT, pspec);
 
        /**
-        * GsApp:rating:
+        * GsReview:rating:
         */
        pspec = g_param_spec_int ("rating", NULL, NULL,
                                  -1, 100, -1,
@@ -413,7 +526,7 @@ gs_review_class_init (GsReviewClass *klass)
        g_object_class_install_property (object_class, PROP_RATING, pspec);
 
        /**
-        * GsApp:flags:
+        * GsReview:flags:
         */
        pspec = g_param_spec_uint64 ("flags", NULL, NULL,
                                     GS_REVIEW_FLAG_NONE,
@@ -423,7 +536,7 @@ gs_review_class_init (GsReviewClass *klass)
        g_object_class_install_property (object_class, PROP_FLAGS, pspec);
 
        /**
-        * GsApp:version:
+        * GsReview:version:
         */
        pspec = g_param_spec_string ("version", NULL, NULL,
                                     NULL,
@@ -431,7 +544,7 @@ gs_review_class_init (GsReviewClass *klass)
        g_object_class_install_property (object_class, PROP_VERSION, pspec);
 
        /**
-        * GsApp:reviewer:
+        * GsReview:reviewer:
         */
        pspec = g_param_spec_string ("reviewer", NULL, NULL,
                                     NULL,
@@ -439,7 +552,7 @@ gs_review_class_init (GsReviewClass *klass)
        g_object_class_install_property (object_class, PROP_REVIEWER, pspec);
 
        /**
-        * GsApp:date:
+        * GsReview:date:
         */
        pspec = g_param_spec_object ("date", NULL, NULL,
                                     GS_TYPE_REVIEW,
diff --git a/src/gs-review.h b/src/gs-review.h
index aadfd38..78f169b 100644
--- a/src/gs-review.h
+++ b/src/gs-review.h
@@ -1,6 +1,7 @@
  /* -*- Mode: C; tab-width: 8; indent-tabs-mode: t; c-basic-offset: 8 -*-
  *
  * Copyright (C) 2016 Canonical Ltd.
+ * Copyright (C) 2016 Richard Hughes <richard hughsie com>
  *
  * Licensed under the GNU General Public License Version 2
  *
@@ -30,6 +31,17 @@ G_BEGIN_DECLS
 
 G_DECLARE_FINAL_TYPE (GsReview, gs_review, GS, REVIEW, GObject)
 
+/**
+ * GsReviewAction:
+ * @GS_REVIEW_ACTION_SUBMIT:   Submit a new review
+ * @GS_REVIEW_ACTION_UPVOTE:   Upvote an existing review
+ * @GS_REVIEW_ACTION_DOWNVOTE: Downvote an existing review
+ * @GS_REVIEW_ACTION_REPORT:   Report an existing review
+ * @GS_REVIEW_ACTION_REMOVE:   Remove a review written by the user
+ * @GS_REVIEW_ACTION_DISMISS:  Dismiss (ignore) a review when moderating
+ *
+ * The review action.
+ **/
 typedef enum {
        GS_REVIEW_ACTION_SUBMIT,
        GS_REVIEW_ACTION_UPVOTE,
@@ -37,13 +49,23 @@ typedef enum {
        GS_REVIEW_ACTION_REPORT,
        GS_REVIEW_ACTION_REMOVE,
        GS_REVIEW_ACTION_DISMISS,
+       /*< private >*/
        GS_REVIEW_ACTION_LAST
 } GsReviewAction;
 
+/**
+ * GsReviewFlags:
+ * @GS_REVIEW_FLAG_NONE:       No special flags set
+ * @GS_REVIEW_FLAG_SELF:       The user wrote the review themselves
+ * @GS_REVIEW_FLAG_VOTED:      The user voted on the review
+ *
+ * The flags for the review.
+ **/
 typedef enum {
        GS_REVIEW_FLAG_NONE     = 0,
-       GS_REVIEW_FLAG_SELF     = 1 << 0,       /* user wrote the review themselves */
-       GS_REVIEW_FLAG_VOTED    = 1 << 1,       /* user voted on the review */
+       GS_REVIEW_FLAG_SELF     = 1 << 0,
+       GS_REVIEW_FLAG_VOTED    = 1 << 1,
+       /*< private >*/
        GS_REVIEW_FLAG_LAST
 } GsReviewFlags;
 
@@ -83,9 +105,9 @@ void          gs_review_set_date                     (GsReview       *review,
 
 GsReviewFlags   gs_review_get_flags                    (GsReview       *review);
 void            gs_review_set_flags                    (GsReview       *review,
-                                                        GsReviewFlags   state);
+                                                        GsReviewFlags   flags);
 void            gs_review_add_flags                    (GsReview       *review,
-                                                        GsReviewFlags   state);
+                                                        GsReviewFlags   flags);
 
 const gchar    *gs_review_get_metadata_item            (GsReview       *review,
                                                         const gchar    *key);
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]