[gucharmap] Add introspection annotations and missing docs.

[Ignacio Casal Quinteiro <icq src gnome org>]

commit 8aa04250299ef70b0ec851f5da0f1b364ecf7c47
Author: Ignacio Casal Quinteiro <icq gnome org>
Date:   Mon Dec 20 14:41:33 2010 +0100

    Add introspection annotations and missing docs.

 gucharmap/gucharmap-chapters-model.c        |   13 ++++----
 gucharmap/gucharmap-chapters-view.c         |   28 ++++++++++++++----
 gucharmap/gucharmap-charmap.c               |   41 ++++++++++++++++++++++++++-
 gucharmap/gucharmap-chartable.c             |    8 ++--
 gucharmap/gucharmap-chartable.h             |    6 ++--
 gucharmap/gucharmap-script-codepoint-list.c |    2 +-
 gucharmap/gucharmap-unicode-info.c          |   38 +++++++++++++++++++------
 gucharmap/gucharmap-unicode-info.h          |   22 +++++++-------
 8 files changed, 117 insertions(+), 41 deletions(-)
---
diff --git a/gucharmap/gucharmap-chapters-model.c b/gucharmap/gucharmap-chapters-model.c
index 8fdf47a..7fd10b3 100644
--- a/gucharmap/gucharmap-chapters-model.c
+++ b/gucharmap/gucharmap-chapters-model.c
@@ -72,9 +72,9 @@ gucharmap_chapters_model_class_init (GucharmapChaptersModelClass *klass)
  * Creates a new #GucharmapCodepointList representing the characters in the
  * current chapter.
  *
- * Return value: the newly-created #GucharmapCodepointList, or NULL if
- * there is no chapter selected. The caller should release the result with
- * g_object_unref() when finished.
+ * Return value: (transfer full): the newly-created #GucharmapCodepointList,
+ * or NULL if there is no chapter selected. The caller should release the
+ * result with g_object_unref() when finished.
  **/
 GucharmapCodepointList * 
 gucharmap_chapters_model_get_codepoint_list (GucharmapChaptersModel *chapters,
@@ -86,11 +86,12 @@ gucharmap_chapters_model_get_codepoint_list (GucharmapChaptersModel *chapters,
 }
 
 /**
- * gucharmap_chapters_model_get_codepoint_list:
+ * gucharmap_chapters_model_get_book_codepoint_list:
  * @chapters: a #GucharmapChaptersModel
  *
- * Return value: a reference to a #GucharmapCodepointList representing all the characters
- * in all the chapters. It should not be modified, but must be g_object_unref()'d after use.
+ * Return value: (transfer full): a reference to a #GucharmapCodepointList
+ * representing all the characters in all the chapters. It should not be
+ * modified, but must be g_object_unref()'d after use.
  **/
 GucharmapCodepointList *
 gucharmap_chapters_model_get_book_codepoint_list (GucharmapChaptersModel *chapters)
diff --git a/gucharmap/gucharmap-chapters-view.c b/gucharmap/gucharmap-chapters-view.c
index 74dba55..556e0a5 100644
--- a/gucharmap/gucharmap-chapters-view.c
+++ b/gucharmap/gucharmap-chapters-view.c
@@ -79,12 +79,27 @@ gucharmap_chapters_view_class_init (GucharmapChaptersViewClass *klass)
 
 G_DEFINE_TYPE (GucharmapChaptersView, gucharmap_chapters_view, GTK_TYPE_TREE_VIEW)
 
+/**
+ * gucharmap_chapters_view_new:
+ *
+ * Creates a new #GucharmapChaptersView object.
+ *
+ * Returns: (transfer full): a new #GucharmapChaptersView
+ */
 GtkWidget * 
 gucharmap_chapters_view_new (void)
 {
   return g_object_new (gucharmap_chapters_view_get_type (), NULL);
 }
 
+/**
+ * gucharmap_chapters_view_get_model:
+ * @view: a #GucharmapChaptersView
+ *
+ * Gets the #GucharmapChaptersModel of #view.
+ *
+ * Returns: (transfer none): the #GucharmapChaptersModel
+ */
 GucharmapChaptersModel *
 gucharmap_chapters_view_get_model (GucharmapChaptersView *view)
 {
@@ -241,9 +256,9 @@ gucharmap_chapters_view_select_character (GucharmapChaptersView *view,
  * Creates a new #GucharmapCodepointList representing the characters in the
  * current chapter.
  *
- * Return value: the newly-created #GucharmapCodepointList, or NULL if
- * there is no chapter selected. The caller should release the result with
- * g_object_unref() when finished.
+ * Return value: (transfer full): the newly-created #GucharmapCodepointList,
+ * or NULL if there is no chapter selected. The caller should release the
+ * result with g_object_unref() when finished.
  **/
 GucharmapCodepointList * 
 gucharmap_chapters_view_get_codepoint_list (GucharmapChaptersView *view)
@@ -262,11 +277,12 @@ gucharmap_chapters_view_get_codepoint_list (GucharmapChaptersView *view)
 }
 
 /**
- * gucharmap_chapters_view_get_codepoint_list:
+ * gucharmap_chapters_view_get_book_codepoint_list:
  * @view: a #GucharmapChaptersView
  *
- * Return value: a reference to a #GucharmapCodepointList representing all the characters
- * in all the chapters. It should not be modified, but must be g_object_unref()'d after use.
+ * Return value: (transfer full): a reference to a #GucharmapCodepointList representing
+ * all the characters in all the chapters. It should not be modified, but must
+ * be g_object_unref()'d after use.
  **/
 GucharmapCodepointList *
 gucharmap_chapters_view_get_book_codepoint_list (GucharmapChaptersView *view)
diff --git a/gucharmap/gucharmap-charmap.c b/gucharmap/gucharmap-charmap.c
index b2ddccc..9787528 100644
--- a/gucharmap/gucharmap-charmap.c
+++ b/gucharmap/gucharmap-charmap.c
@@ -1474,6 +1474,12 @@ gucharmap_charmap_previous_chapter (GucharmapCharmap *charmap)
   gucharmap_chapters_view_previous (priv->chapters_view);
 }
 
+/**
+ * gucharmap_charmap_get_chartable:
+ * @charmap: a #GucharmapCharmap
+ *
+ * Returns: (transfer none): a #GucharmapChartable
+ */
 GucharmapChartable *
 gucharmap_charmap_get_chartable (GucharmapCharmap *charmap)
 {
@@ -1510,6 +1516,15 @@ gucharmap_charmap_set_chapters_model (GucharmapCharmap  *charmap,
   g_object_thaw_notify (object);
 }
 
+/**
+ * gucharmap_charmap_get_chapters_model:
+ * @charmap: a #GucharmapCharmap
+ *
+ * Gets the #GucharmapChaptersModel associated with the #GucharmapChaptersView
+ * of @charmap.
+ *
+ * Returns: (transfer none): a #GucharmapChaptersModel
+ */
 GucharmapChaptersModel *
 gucharmap_charmap_get_chapters_model (GucharmapCharmap *charmap)
 {
@@ -1518,14 +1533,29 @@ gucharmap_charmap_get_chapters_model (GucharmapCharmap *charmap)
   return gucharmap_chapters_view_get_model (priv->chapters_view);
 }
 
+/**
+ * gucharmap_charmap_get_chapters_view:
+ * @charmap: a #GucharmapCharmap
+ *
+ * Gets the #GucharmapChaptersView of @charmap
+ *
+ * Returns: (transfer none): the #GucharmapChaptersView
+ */
 GucharmapChaptersView *
-gucharmap_charmap_get_chapters_view  (GucharmapCharmap *charmap)
+gucharmap_charmap_get_chapters_view (GucharmapCharmap *charmap)
 {
   GucharmapCharmapPrivate *priv = charmap->priv;
 
   return priv->chapters_view;
 }
 
+/**
+ * gucharmap_charmap_get_book_codepoint_list:
+ * @charmap: a #GucharmapCharmap
+ *
+ * Returns: (transfer full): the GucharmapCodepointList. Must be freed with
+ * g_object_unref().
+ */
 GucharmapCodepointList *
 gucharmap_charmap_get_book_codepoint_list (GucharmapCharmap *charmap)
 {
@@ -1605,6 +1635,15 @@ gucharmap_charmap_get_active_page (GucharmapCharmap *charmap)
   return priv->active_page;
 }
 
+/**
+ * gucharmap_charmap_get_active_codepoint_list:
+ * @charmap: a #GucharmapCharmap
+ *
+ * Gets the @GucharmapCodepointList associated with the #GucharmapChartable of
+ * @charmap.
+ *
+ * Returns: (transfer none): the #GucharmapCodepointList
+ */
 GucharmapCodepointList *
 gucharmap_charmap_get_active_codepoint_list (GucharmapCharmap *charmap)
 {
diff --git a/gucharmap/gucharmap-chartable.c b/gucharmap/gucharmap-chartable.c
index 47ef16a..6c97a20 100644
--- a/gucharmap/gucharmap-chartable.c
+++ b/gucharmap/gucharmap-chartable.c
@@ -2783,7 +2783,7 @@ gucharmap_chartable_get_active_character (GucharmapChartable *chartable)
 }
 
 /**
- * gucharmap_chartable_get_active_character:
+ * gucharmap_chartable_set_active_character:
  * @chartable: a #GucharmapChartable
  * @wc: a unicode character (UTF-32)
  *
@@ -2838,9 +2838,9 @@ gucharmap_chartable_get_snap_pow2 (GucharmapChartable *chartable)
 }
 
 /**
- * gucharmap_chartable_get_active_character:
+ * gucharmap_chartable_set_codepoint_list:
  * @chartable: a #GucharmapChartable
- * @list: a #GucharmapCodepointList
+ * @codepoint_list: a #GucharmapCodepointList
  *
  * Sets the codepoint list to show in the character table.
  */
@@ -2882,7 +2882,7 @@ gucharmap_chartable_set_codepoint_list (GucharmapChartable     *chartable,
  * gucharmap_chartable_get_codepoint_list:
  * @chartable: a #GucharmapChartable
  *
- * Returns: the current codepoint list
+ * Returns: (transfer none): the current codepoint list
  */
 GucharmapCodepointList *
 gucharmap_chartable_get_codepoint_list (GucharmapChartable *chartable)
diff --git a/gucharmap/gucharmap-chartable.h b/gucharmap/gucharmap-chartable.h
index 7a948f4..e4b109c 100644
--- a/gucharmap/gucharmap-chartable.h
+++ b/gucharmap/gucharmap-chartable.h
@@ -76,8 +76,8 @@ void gucharmap_chartable_set_font_fallback (GucharmapChartable *chartable,
                                             gboolean enable_font_fallback);
 gboolean gucharmap_chartable_get_font_fallback (GucharmapChartable *chartable);
 gunichar gucharmap_chartable_get_active_character (GucharmapChartable *chartable);
-void gucharmap_chartable_set_active_character (GucharmapChartable *chartable, 
-                                               gunichar uc);
+void gucharmap_chartable_set_active_character (GucharmapChartable *chartable,
+                                               gunichar wc);
 void gucharmap_chartable_set_zoom_enabled (GucharmapChartable *chartable,
                                            gboolean enabled);
 gboolean gucharmap_chartable_get_zoom_enabled (GucharmapChartable *chartable);
@@ -85,7 +85,7 @@ void gucharmap_chartable_set_snap_pow2 (GucharmapChartable *chartable,
                                         gboolean snap);
 gboolean gucharmap_chartable_get_snap_pow2 (GucharmapChartable *chartable);
 void gucharmap_chartable_set_codepoint_list (GucharmapChartable         *chartable,
-                                             GucharmapCodepointList *list);
+                                             GucharmapCodepointList *codepoint_list);
 GucharmapCodepointList * gucharmap_chartable_get_codepoint_list (GucharmapChartable *chartable);
 
 G_END_DECLS
diff --git a/gucharmap/gucharmap-script-codepoint-list.c b/gucharmap/gucharmap-script-codepoint-list.c
index 9f6812b..2724302 100644
--- a/gucharmap/gucharmap-script-codepoint-list.c
+++ b/gucharmap/gucharmap-script-codepoint-list.c
@@ -411,7 +411,7 @@ gucharmap_script_codepoint_list_append_script (GucharmapScriptCodepointList  *li
  * modified or free; the array itself however is allocated and should
  * be freed with g_free().
  *
- * Returns: a newly allocated %NULL-terminated array of strings
+ * Returns: (transfer container): a newly allocated %NULL-terminated array of strings
  **/
 const gchar **
 gucharmap_unicode_list_scripts (void)
diff --git a/gucharmap/gucharmap-unicode-info.c b/gucharmap/gucharmap-unicode-info.c
index 5194af0..afee214 100644
--- a/gucharmap/gucharmap-unicode-info.c
+++ b/gucharmap/gucharmap-unicode-info.c
@@ -394,8 +394,13 @@ gucharmap_get_nameslist_exes (gunichar uc)
   return exes;
 }
 
-/* returns newly allocated null-terminated array of gchar* */
-/* the items are const, but the array should be freed by the caller */
+/**
+ * gucharmap_get_nameslist_equals:
+ * @uc: a gunichar
+ *
+ * Returns: (transfer container): newly allocated null-terminated array of gchar*
+ * the items are const, but the array should be freed by the caller
+ */
 G_CONST_RETURN gchar **
 gucharmap_get_nameslist_equals (gunichar uc)
 {
@@ -420,8 +425,13 @@ gucharmap_get_nameslist_equals (gunichar uc)
   return equals;
 }
 
-/* returns newly allocated null-terminated array of gchar* */
-/* the items are const, but the array should be freed by the caller */
+/**
+ * gucharmap_get_nameslist_stars:
+ * @uc: a #gunichar
+ *
+ * Returns: (transfer container): newly allocated null-terminated array of gchar*
+ * the items are const, but the array should be freed by the caller
+ */
 G_CONST_RETURN gchar **
 gucharmap_get_nameslist_stars (gunichar uc)
 {
@@ -446,8 +456,13 @@ gucharmap_get_nameslist_stars (gunichar uc)
   return stars;
 }
 
-/* returns newly allocated null-terminated array of gchar* */
-/* the items are const, but the array should be freed by the caller */
+/**
+ * gucharmap_get_nameslist_pounds:
+ * @uc: a #gunichar
+ *
+ * Returns: (transfer container): newly allocated null-terminated array of gchar*
+ * the items are const, but the array should be freed by the caller
+ */
 G_CONST_RETURN gchar **
 gucharmap_get_nameslist_pounds (gunichar uc)
 {
@@ -472,8 +487,13 @@ gucharmap_get_nameslist_pounds (gunichar uc)
   return pounds;
 }
 
-/* returns newly allocated null-terminated array of gchar* */
-/* the items are const, but the array should be freed by the caller */
+/**
+ * gucharmap_get_nameslist_colons:
+ * @uc: a #gunichar
+ *
+ * Returns: (transfer container): newly allocated null-terminated array of gchar*
+ * the items are const, but the array should be freed by the caller
+ */
 G_CONST_RETURN gchar **
 gucharmap_get_nameslist_colons (gunichar uc)
 {
@@ -560,7 +580,7 @@ gucharmap_unichar_to_printable_utf8 (gunichar uc, gchar *outbuf)
 
 /**
  * gucharmap_unichar_type:
- * @c: a Unicode character
+ * @uc: a Unicode character
  * 
  * Classifies a Unicode character by type.
  * 
diff --git a/gucharmap/gucharmap-unicode-info.h b/gucharmap/gucharmap-unicode-info.h
index 80e76e3..5b086c2 100644
--- a/gucharmap/gucharmap-unicode-info.h
+++ b/gucharmap/gucharmap-unicode-info.h
@@ -48,7 +48,7 @@ typedef enum {
 G_CONST_RETURN gchar *  gucharmap_get_unicode_name                (gunichar uc);
 G_CONST_RETURN gchar *  gucharmap_get_unicode_data_name           (gunichar uc);
 gint                    gucharmap_get_unicode_data_name_count     (void);
-GucharmapUnicodeVersion gucharmap_get_unicode_version             (gunichar wc);
+GucharmapUnicodeVersion gucharmap_get_unicode_version             (gunichar uc);
 G_CONST_RETURN gchar *  gucharmap_get_unicode_category_name       (gunichar uc);
 gint                    gucharmap_get_unihan_count                (void);
 G_CONST_RETURN gchar *  gucharmap_get_unicode_kDefinition         (gunichar uc);
@@ -60,17 +60,17 @@ G_CONST_RETURN gchar *  gucharmap_get_unicode_kJapaneseKun        (gunichar uc);
 G_CONST_RETURN gchar *  gucharmap_get_unicode_kJapaneseOn         (gunichar uc);
 
 /* nameslist stuff */
-G_CONST_RETURN gchar ** gucharmap_get_nameslist_stars             (gunichar  wc);
-G_CONST_RETURN gchar ** gucharmap_get_nameslist_equals            (gunichar  wc);
-gunichar *              gucharmap_get_nameslist_exes              (gunichar  wc);
-G_CONST_RETURN gchar ** gucharmap_get_nameslist_pounds            (gunichar  wc);
-G_CONST_RETURN gchar ** gucharmap_get_nameslist_colons            (gunichar  wc);
-gboolean                gucharmap_unichar_validate                (gunichar  wc);
-gint                    gucharmap_unichar_to_printable_utf8       (gunichar  wc, 
+G_CONST_RETURN gchar ** gucharmap_get_nameslist_stars             (gunichar  uc);
+G_CONST_RETURN gchar ** gucharmap_get_nameslist_equals            (gunichar  uc);
+gunichar *              gucharmap_get_nameslist_exes              (gunichar  uc);
+G_CONST_RETURN gchar ** gucharmap_get_nameslist_pounds            (gunichar  uc);
+G_CONST_RETURN gchar ** gucharmap_get_nameslist_colons            (gunichar  uc);
+gboolean                gucharmap_unichar_validate                (gunichar  uc);
+gint                    gucharmap_unichar_to_printable_utf8       (gunichar  uc,
                                                                    gchar    *outbuf);
-GUnicodeType            gucharmap_unichar_type                    (gunichar  wc);
-gboolean                gucharmap_unichar_isdefined               (gunichar  wc);
-gboolean                gucharmap_unichar_isgraph                 (gunichar  wc);
+GUnicodeType            gucharmap_unichar_type                    (gunichar  uc);
+gboolean                gucharmap_unichar_isdefined               (gunichar  uc);
+gboolean                gucharmap_unichar_isgraph                 (gunichar  uc);
 
 /* defined in gucharmap-script-codepoint-list.c */
 G_CONST_RETURN gchar ** gucharmap_unicode_list_scripts            (void);