[devhelp: 2/2] Book: fix/improve the gtk-doc comments

From: Sébastien Wilmet <swilmet src gnome org>
To: commits-list gnome org
Cc:
Subject: [devhelp: 2/2] Book: fix/improve the gtk-doc comments
Date: Sat, 29 Apr 2017 11:01:06 +0000 (UTC)
commit 5757637f33dfd8aad6502d4e3d735ef42d62b808
Author: Sébastien Wilmet <swilmet gnome org>
Date:   Sat Apr 29 12:18:14 2017 +0200

    Book: fix/improve the gtk-doc comments
    
    There were several errors.

 src/dh-book.c |  109 ++++++++++++++++++++++++++-------------------------------
 1 files changed, 50 insertions(+), 59 deletions(-)
---
diff --git a/src/dh-book.c b/src/dh-book.c
index cb21513..b438c75 100644
--- a/src/dh-book.c
+++ b/src/dh-book.c
@@ -141,7 +141,7 @@ dh_book_class_init (DhBookClass *klass)
 
         /**
          * DhBook::enabled:
-         * @book: the book on which the signal is emitted
+         * @book: the book on which the signal is emitted.
          */
         signals[BOOK_ENABLED] =
                 g_signal_new ("enabled",
@@ -155,7 +155,7 @@ dh_book_class_init (DhBookClass *klass)
 
         /**
          * DhBook::disabled:
-         * @book: the book on which the signal is emitted
+         * @book: the book on which the signal is emitted.
          */
         signals[BOOK_DISABLED] =
                 g_signal_new ("disabled",
@@ -169,7 +169,7 @@ dh_book_class_init (DhBookClass *klass)
 
         /**
          * DhBook::updated:
-         * @book: the book on which the signal is emitted
+         * @book: the book on which the signal is emitted.
          */
         signals[BOOK_UPDATED] =
                 g_signal_new ("updated",
@@ -183,7 +183,7 @@ dh_book_class_init (DhBookClass *klass)
 
         /**
          * DhBook::deleted:
-         * @book: the book on which the signal is emitted
+         * @book: the book on which the signal is emitted.
          */
         signals[BOOK_DELETED] =
                 g_signal_new ("deleted",
@@ -224,9 +224,7 @@ unref_node_link (GNode    *node,
  * dh_book_new:
  * @book_path: the path of the book
  *
- * Create a new #DhBook object.
- *
- * Returns: a new #DhBook object
+ * Returns: a new #DhBook object.
  */
 DhBook *
 dh_book_new (const gchar *book_path)
@@ -370,11 +368,10 @@ book_monitor_event_cb (GFileMonitor      *file_monitor,
 
 /**
  * dh_book_get_keywords:
- * @book: a #DhBook object
- *
- * Get the #GList of keywords associated with the book.
+ * @book: a #DhBook.
  *
- * Returns: (element-type utf8) (transfer none) (nullable): the keywords associated with the book
+ * Returns: (element-type DhLink) (transfer none) (nullable): the list of
+ * #DhLink's part of @book.
  */
 GList *
 dh_book_get_keywords (DhBook *book)
@@ -390,11 +387,10 @@ dh_book_get_keywords (DhBook *book)
 
 /**
  * dh_book_get_completions:
- * @book: a #DhBook object
+ * @book: a #DhBook.
  *
- * Get the #GList of completions associated with the book.
- *
- * Returns: (element-type utf8) (transfer full) (nullable): the completions associated with the book
+ * Returns: (element-type utf8) (transfer none) (nullable): the completions
+ * associated with the book.
  */
 GList *
 dh_book_get_completions (DhBook *book)
@@ -435,11 +431,9 @@ dh_book_get_completions (DhBook *book)
 
 /**
  * dh_book_get_tree:
- * @book: a #DhBook object
- *
- * Get the #GNode representing the book tree.
+ * @book: a #DhBook.
  *
- * Returns: (transfer none) (nullable): the book tree
+ * Returns: (transfer none) (nullable): the tree of #DhLink's part of the @book.
  */
 GNode *
 dh_book_get_tree (DhBook *book)
@@ -455,11 +449,9 @@ dh_book_get_tree (DhBook *book)
 
 /**
  * dh_book_get_name:
- * @book: a #DhBook object
+ * @book: a #DhBook.
  *
- * Get the book name.
- *
- * Returns: the book name
+ * Returns: the book name.
  */
 const gchar *
 dh_book_get_name (DhBook *book)
@@ -475,11 +467,9 @@ dh_book_get_name (DhBook *book)
 
 /**
  * dh_book_get_title:
- * @book: a #DhBook object
- *
- * Get the book title.
+ * @book: a #DhBook.
  *
- * Returns: the book title
+ * Returns: the book title.
  */
 const gchar *
 dh_book_get_title (DhBook *book)
@@ -495,11 +485,9 @@ dh_book_get_title (DhBook *book)
 
 /**
  * dh_book_get_language:
- * @book: a #DhBook object
- *
- * Get the book language.
+ * @book: a #DhBook.
  *
- * Returns: the book language
+ * Returns: the book language.
  */
 const gchar *
 dh_book_get_language (DhBook *book)
@@ -515,11 +503,9 @@ dh_book_get_language (DhBook *book)
 
 /**
  * dh_book_get_path:
- * @book: a #DhBook object
+ * @book: a #DhBook.
  *
- * Get the book path.
- *
- * Returns: the book path
+ * Returns: the book path.
  */
 const gchar *
 dh_book_get_path (DhBook *book)
@@ -535,11 +521,9 @@ dh_book_get_path (DhBook *book)
 
 /**
  * dh_book_get_enabled:
- * @book: a #DhBook object
- *
- * Get the current state of the book.
+ * @book: a #DhBook.
  *
- * Returns: %TRUE if the book is enabled
+ * Returns: whether the book is enabled.
  */
 gboolean
 dh_book_get_enabled (DhBook *book)
@@ -555,10 +539,10 @@ dh_book_get_enabled (DhBook *book)
 
 /**
  * dh_book_set_enabled:
- * @book: a #DhBook object
- * @enabled: %TRUE to enable the book
+ * @book: a #DhBook.
+ * @enabled: the new value.
  *
- * Enable or disable completely the book.
+ * Enables or disables the book.
  */
 void
 dh_book_set_enabled (DhBook   *book,
@@ -579,12 +563,13 @@ dh_book_set_enabled (DhBook   *book,
 
 /**
  * dh_book_cmp_by_path:
- * @a: a #DhBook object
- * @b: a second #DhBook object
+ * @a: a #DhBook.
+ * @b: a #DhBook.
  *
- * Compare the #DhBook @a and @b by their paths.
+ * Compares the #DhBook's by their paths.
  *
- * Returns: an integer less than, equal to, or greater than zero, if @a is <, == or > than @b.
+ * Returns: an integer less than, equal to, or greater than zero, if @a is <, ==
+ * or > than @b.
  */
 gint
 dh_book_cmp_by_path (DhBook *a,
@@ -604,12 +589,14 @@ dh_book_cmp_by_path (DhBook *a,
 
 /**
  * dh_book_cmp_by_path_str:
- * @a: a #DhBook object
- * @b_path: a path to a book
+ * @a: a #DhBook.
+ * @b_path: a path to a book.
  *
- * Compare the path of the #DhBook a with @b_path.
+ * Compares the paths of the #DhBook @a with @b_path.
  *
- * Returns: an integer less than, equal to, or greater than zero, if the path of @a is <, == or > than 
@b_path.
+ * Returns: an integer less than, equal to, or greater than zero, if the path of
+ * @a is <, == or > than @b_path.
+ * Deprecated: Use dh_book_cmp_by_path() instead.
  */
 gint
 dh_book_cmp_by_path_str (DhBook      *a,
@@ -627,12 +614,13 @@ dh_book_cmp_by_path_str (DhBook      *a,
 
 /**
  * dh_book_cmp_by_name:
- * @a: a #DhBook object
- * @b: a second #DhBook object
+ * @a: a #DhBook.
+ * @b: a #DhBook.
  *
- * Compare the #DhBook @a and @b by their name.
+ * Compares the #DhBook's by their name.
  *
- * Returns: an integer less than, equal to, or greater than zero, if @a is <, == or > than @b.
+ * Returns: an integer less than, equal to, or greater than zero, if @a is <, ==
+ * or > than @b.
  */
 gint
 dh_book_cmp_by_name (DhBook *a,
@@ -660,7 +648,9 @@ dh_book_cmp_by_name (DhBook *a,
  *
  * Compare the name of the #DhBook a with @b_name.
  *
- * Returns: an integer less than, equal to, or greater than zero, if the name of @a is <, == or > than 
@b_name.
+ * Returns: an integer less than, equal to, or greater than zero, if the name of
+ * @a is <, == or > than @b_name.
+ * Deprecated: Use dh_book_cmp_by_name() instead.
  */
 gint
 dh_book_cmp_by_name_str (DhBook      *a,
@@ -681,12 +671,13 @@ dh_book_cmp_by_name_str (DhBook      *a,
 
 /**
  * dh_book_cmp_by_title:
- * @a: a #DhBook object
- * @b: a second #DhBook object
+ * @a: a #DhBook.
+ * @b: a #DhBook.
  *
- * Compare the #DhBook @a and @b by their title.
+ * Compares the #DhBook's by their title.
  *
- * Returns: an integer less than, equal to, or greater than zero, if @a is <, == or > than @b.
+ * Returns: an integer less than, equal to, or greater than zero, if @a is <, ==
+ * or > than @b.
  */
 gint
 dh_book_cmp_by_title (DhBook *a,
[Date Prev][Date Next] [Thread Prev][Thread Next] [Thread Index] [Date Index] [Author Index]