[devhelp/wip/tintou/more-annotations] Improve the documentation coverage



commit a43bad749216e111e98637bd4a6681685b2be6d7
Author: Corentin Noël <corentin elementary io>
Date:   Fri Oct 28 02:29:03 2016 +0200

    Improve the documentation coverage
    
    Added the minimal annotations
    All methods are now documented
    https://bugzilla.gnome.org/show_bug.cgi?id=770785

 src/dh-app.c            |   65 +++++++++++++++++++++-
 src/dh-app.h            |   16 +++---
 src/dh-assistant-view.c |   36 +++++++++++-
 src/dh-assistant.c      |   17 ++++++
 src/dh-book-manager.c   |   76 +++++++++++++++++++++++++
 src/dh-book-tree.c      |   29 +++++++++-
 src/dh-book-tree.h      |    2 +-
 src/dh-book.c           |  141 ++++++++++++++++++++++++++++++++++++++++++++++-
 src/dh-keyword-model.c  |   26 +++++++++
 src/dh-keyword-model.h  |    2 +-
 src/dh-language.c       |   65 +++++++++++++++++++++-
 src/dh-link.c           |  119 +++++++++++++++++++++++++++++++++++++++
 src/dh-sidebar.c        |   51 ++++++++++++++---
 src/dh-sidebar.h        |    8 +-
 src/dh-window.c         |   31 ++++++++++-
 15 files changed, 650 insertions(+), 34 deletions(-)
---
diff --git a/src/dh-app.c b/src/dh-app.c
index 8e9aa5b..e474df4 100644
--- a/src/dh-app.c
+++ b/src/dh-app.c
@@ -34,8 +34,14 @@ typedef struct {
 
 G_DEFINE_TYPE_WITH_PRIVATE (DhApp, dh_app, GTK_TYPE_APPLICATION);
 
-/******************************************************************************/
-
+/**
+ * dh_app_peek_book_manager:
+ * @app: a #DhApp object
+ *
+ * Get the associated #DhBookManager.
+ *
+ * Returns: (transfer none): the book manager associated with this
+ */
 DhBookManager *
 dh_app_peek_book_manager (DhApp *app)
 {
@@ -48,6 +54,14 @@ dh_app_peek_book_manager (DhApp *app)
         return priv->book_manager;
 }
 
+/**
+ * dh_app_peek_first_window:
+ * @app: a #DhApp object
+ *
+ * Get the first #DhWindow.
+ *
+ * Returns: (transfer none): the first window
+ */
 GtkWindow *
 dh_app_peek_first_window (DhApp *app)
 {
@@ -70,6 +84,14 @@ dh_app_peek_first_window (DhApp *app)
         return dh_app_peek_first_window (app);
 }
 
+/**
+ * dh_app_peek_assistant:
+ * @app: a #DhApp object
+ *
+ * Get the associated #DhAssistant.
+ *
+ * Returns: (transfer none): the assistant
+ */
 GtkWindow *
 dh_app_peek_assistant (DhApp *app)
 {
@@ -114,6 +136,12 @@ _dh_app_has_app_menu (DhApp *app)
 /******************************************************************************/
 /* Application action activators */
 
+/**
+ * dh_app_new_window:
+ * @app: a #DhApp object
+ *
+ * Create a new #DhWindow.
+ */
 void
 dh_app_new_window (DhApp *app)
 {
@@ -122,6 +150,12 @@ dh_app_new_window (DhApp *app)
         g_action_group_activate_action (G_ACTION_GROUP (app), "new-window", NULL);
 }
 
+/**
+ * dh_app_quit:
+ * @app: a #DhApp object
+ *
+ * Quit the application.
+ */
 void
 dh_app_quit (DhApp *app)
 {
@@ -130,6 +164,13 @@ dh_app_quit (DhApp *app)
         g_action_group_activate_action (G_ACTION_GROUP (app), "quit", NULL);
 }
 
+/**
+ * dh_app_search:
+ * @app: a #DhApp object
+ * @keyword: the search request
+ *
+ * Search for @keyword in the entire application.
+ */
 void
 dh_app_search (DhApp *app,
                const gchar *keyword)
@@ -139,6 +180,13 @@ dh_app_search (DhApp *app,
         g_action_group_activate_action (G_ACTION_GROUP (app), "search", g_variant_new_string (keyword));
 }
 
+/**
+ * dh_app_search_assistant:
+ * @app: a #DhApp object
+ * @keyword: the search request
+ *
+ * Search for @keyword in the entire application with a #DhAssistant.
+ */
 void
 dh_app_search_assistant (DhApp *app,
                          const gchar *keyword)
@@ -148,6 +196,12 @@ dh_app_search_assistant (DhApp *app,
         g_action_group_activate_action (G_ACTION_GROUP (app), "search-assistant", g_variant_new_string 
(keyword));
 }
 
+/**
+ * dh_app_raise:
+ * @app: a #DhApp object
+ *
+ * Present the main window of the application.
+ */
 void
 dh_app_raise (DhApp *app)
 {
@@ -466,6 +520,13 @@ dh_app_activate (GApplication *application)
 
 /******************************************************************************/
 
+/**
+ * dh_app_new:
+ *
+ * Create a new #DhApp object.
+ *
+ * Returns: a new #DhApp object
+ */
 DhApp *
 dh_app_new (void)
 {
diff --git a/src/dh-app.h b/src/dh-app.h
index 9280f65..bd7c88d 100644
--- a/src/dh-app.h
+++ b/src/dh-app.h
@@ -47,17 +47,17 @@ GType dh_app_get_type (void) G_GNUC_CONST;
 
 DhApp         *dh_app_new               (void);
 
-DhBookManager *dh_app_peek_book_manager (DhApp *self);
-GtkWindow     *dh_app_peek_first_window (DhApp *self);
-GtkWindow     *dh_app_peek_assistant    (DhApp *self);
+DhBookManager *dh_app_peek_book_manager (DhApp *app);
+GtkWindow     *dh_app_peek_first_window (DhApp *app);
+GtkWindow     *dh_app_peek_assistant    (DhApp *app);
 
-void           dh_app_new_window        (DhApp *self);
-void           dh_app_quit              (DhApp *self);
-void           dh_app_search            (DhApp *self,
+void           dh_app_new_window        (DhApp *app);
+void           dh_app_quit              (DhApp *app);
+void           dh_app_search            (DhApp *app,
                                          const gchar *keyword);
-void           dh_app_search_assistant  (DhApp *self,
+void           dh_app_search_assistant  (DhApp *app,
                                          const gchar *keyword);
-void           dh_app_raise             (DhApp *self);
+void           dh_app_raise             (DhApp *app);
 
 gboolean      _dh_app_has_app_menu      (DhApp *app);
 
diff --git a/src/dh-assistant-view.c b/src/dh-assistant-view.c
index 0f859a2..eae2161 100644
--- a/src/dh-assistant-view.c
+++ b/src/dh-assistant-view.c
@@ -135,6 +135,11 @@ dh_assistant_view_class_init (DhAssistantViewClass* klass)
 
         g_type_class_add_private (klass, sizeof (DhAssistantViewPriv));
 
+        /**
+         * DhAssistantView::open-uri:
+         * @view: the view on which the signal is emitted
+         * @uri: the uri to open
+         */
         signals[SIGNAL_OPEN_URI] = g_signal_new ("open-uri",
                                                  G_TYPE_FROM_CLASS (object_class),
                                                  0, 0,
@@ -149,6 +154,13 @@ dh_assistant_view_init (DhAssistantView *view)
 {
 }
 
+/**
+ * dh_assistant_view_new:
+ *
+ * Create a new #DhAssistantView object.
+ *
+ * Returns: a new #DhAssistantView object
+ */
 GtkWidget*
 dh_assistant_view_new (void)
 {
@@ -181,13 +193,13 @@ find_in_buffer (const gchar *buffer,
 
 /**
  * dh_assistant_view_set_link:
- * @view: an devhelp assistant view
- * @link: the #DhLink
+ * @view: a #DhAssistantView object
+ * @link: (nullable): a #DhLink to set or %NULL
  *
  * Open @link in the assistant view, if %NULL the view will be blanked.
  *
- * Return value: %TRUE if the requested link is open, %FALSE otherwise.
- **/
+ * Returns: %TRUE if the requested link is open, %FALSE otherwise
+ */
 gboolean
 dh_assistant_view_set_link (DhAssistantView *view,
                             DhLink          *link)
@@ -398,6 +410,15 @@ dh_assistant_view_set_link (DhAssistantView *view,
         return TRUE;
 }
 
+/**
+ * dh_assistant_view_search:
+ * @view: a #DhAssistantView object
+ * @str: the search query
+ *
+ * Search for @str in the current assistant view.
+ *
+ * Returns: %TRUE if @str was found, %FALSE otherwise
+ */
 gboolean
 dh_assistant_view_search (DhAssistantView *view,
                           const gchar     *str)
@@ -480,6 +501,13 @@ dh_assistant_view_search (DhAssistantView *view,
         return TRUE;
 }
 
+/**
+ * dh_assistant_view_set_book_manager:
+ * @view: a #DhAssistantView object
+ * @book_manager: the new book manager
+ *
+ * Set a new book manager to search in.
+ */
 void
 dh_assistant_view_set_book_manager (DhAssistantView *view,
                                     DhBookManager   *book_manager)
diff --git a/src/dh-assistant.c b/src/dh-assistant.c
index 26e2157..ffb0122 100644
--- a/src/dh-assistant.c
+++ b/src/dh-assistant.c
@@ -115,6 +115,14 @@ dh_assistant_init (DhAssistant *assistant)
                                          FALSE);
 }
 
+/**
+ * dh_assistant_new:
+ * @application: the parent #DhApp
+ *
+ * Create a new #DhAssistant object.
+ *
+ * Returns: a new #DhAssistant object
+ */
 GtkWidget *
 dh_assistant_new (DhApp *application)
 {
@@ -130,6 +138,15 @@ dh_assistant_new (DhApp *application)
         return assistant;
 }
 
+/**
+ * dh_assistant_search:
+ * @assistant: a #DhAssistant object
+ * @str: the search query
+ *
+ * Search for @str in the current assistant.
+ *
+ * Returns: %TRUE if @str was found, %FALSE otherwise
+ */
 gboolean
 dh_assistant_search (DhAssistant *assistant,
                      const gchar *str)
diff --git a/src/dh-book-manager.c b/src/dh-book-manager.c
index 13c5fa2..b10cc6b 100644
--- a/src/dh-book-manager.c
+++ b/src/dh-book-manager.c
@@ -135,6 +135,11 @@ dh_book_manager_class_init (DhBookManagerClass *klass)
         object_class->set_property = dh_book_manager_set_property;
         object_class->get_property = dh_book_manager_get_property;
 
+        /**
+         * DhBookManager::book-created:
+         * @book_manager: the book manager on which the signal is emitted
+         * @book: (type DhBook): the created book
+         */
         signals[BOOK_CREATED] =
                 g_signal_new ("book-created",
                               G_TYPE_FROM_CLASS (klass),
@@ -145,6 +150,11 @@ dh_book_manager_class_init (DhBookManagerClass *klass)
                               G_TYPE_NONE,
                               1,
                               G_TYPE_OBJECT);
+        /**
+         * DhBookManager::book-deleted:
+         * @book_manager: the book manager on which the signal is emitted
+         * @book: (type DhBook): the deleted book
+         */
         signals[BOOK_DELETED] =
                 g_signal_new ("book-deleted",
                               G_TYPE_FROM_CLASS (klass),
@@ -155,6 +165,11 @@ dh_book_manager_class_init (DhBookManagerClass *klass)
                               G_TYPE_NONE,
                               1,
                               G_TYPE_OBJECT);
+        /**
+         * DhBookManager::book-enabled:
+         * @book_manager: the book manager on which the signal is emitted
+         * @book: (type DhBook): the enabled book
+         */
         signals[BOOK_ENABLED] =
                 g_signal_new ("book-enabled",
                               G_TYPE_FROM_CLASS (klass),
@@ -165,6 +180,11 @@ dh_book_manager_class_init (DhBookManagerClass *klass)
                               G_TYPE_NONE,
                               1,
                               G_TYPE_OBJECT);
+        /**
+         * DhBookManager::book-disabled:
+         * @book_manager: the book manager on which the signal is emitted
+         * @book: (type DhBook): the disabled book
+         */
         signals[BOOK_DISABLED] =
                 g_signal_new ("book-disabled",
                               G_TYPE_FROM_CLASS (klass),
@@ -176,6 +196,11 @@ dh_book_manager_class_init (DhBookManagerClass *klass)
                               1,
                               G_TYPE_OBJECT);
 
+        /**
+         * DhBookManager::language-enabled:
+         * @book_manager: the book manager on which the signal is emitted
+         * @language_name: the enabled language name
+         */
         signals[LANGUAGE_ENABLED] =
                 g_signal_new ("language-enabled",
                               G_TYPE_FROM_CLASS (klass),
@@ -186,6 +211,11 @@ dh_book_manager_class_init (DhBookManagerClass *klass)
                               G_TYPE_NONE,
                               1,
                               G_TYPE_STRING);
+        /**
+         * DhBookManager::language-disabled:
+         * @book_manager: the book manager on which the signal is emitted
+         * @language_name: the disabled language name
+         */
         signals[LANGUAGE_DISABLED] =
                 g_signal_new ("language-disabled",
                               G_TYPE_FROM_CLASS (klass),
@@ -348,6 +378,13 @@ book_manager_add_books_in_data_dir (DhBookManager *book_manager,
         g_free (dir);
 }
 
+/**
+ * dh_book_manager_populate:
+ * @book_manager: a #DhBookManager object
+ *
+ * Populate the #DhBookManager with all books found on the system and user
+ * directories.
+ */
 void
 dh_book_manager_populate (DhBookManager *book_manager)
 {
@@ -732,6 +769,14 @@ book_manager_add_from_filepath (DhBookManager *book_manager,
                        book);
 }
 
+/**
+ * dh_book_manager_get_books:
+ * @book_manager: a #DhBookManager object
+ *
+ * Get the #GList of books.
+ *
+ * Returns: (element-type DhBook) (transfer none): the books
+ */
 GList *
 dh_book_manager_get_books (DhBookManager *book_manager)
 {
@@ -744,6 +789,14 @@ dh_book_manager_get_books (DhBookManager *book_manager)
         return priv->books;
 }
 
+/**
+ * dh_book_manager_get_group_by_language:
+ * @book_manager: a #DhBookManager object
+ *
+ * Get whether books should be grouped by language.
+ *
+ * Returns: %TRUE if books should be grouped by language, %FALSE otherwise
+ */
 gboolean
 dh_book_manager_get_group_by_language (DhBookManager *book_manager)
 {
@@ -756,6 +809,13 @@ dh_book_manager_get_group_by_language (DhBookManager *book_manager)
         return priv->group_by_language;
 }
 
+/**
+ * dh_book_manager_set_group_by_language:
+ * @book_manager: a #DhBookManager object
+ * @group_by_language: %TRUE if books should be grouped by language, %FALSE otherwise
+ *
+ * Set whether books should be grouped by language.
+ */
 void
 dh_book_manager_set_group_by_language (DhBookManager *book_manager,
                                        gboolean       group_by_language)
@@ -827,6 +887,15 @@ book_manager_dec_language (DhBookManager *book_manager,
         }
 }
 
+/**
+ * dh_book_manager_get_languages:
+ * @book_manager: a #DhBookManager object
+ *
+ * Get the #GList of languages.
+ *
+ * Returns: (element-type DhLanguage) (transfer none): the list of languages
+ * Deprecated: 3.18: Not used anywhere
+ */
 GList *
 dh_book_manager_get_languages (DhBookManager *book_manager)
 {
@@ -839,6 +908,13 @@ dh_book_manager_get_languages (DhBookManager *book_manager)
         return priv->languages;
 }
 
+/**
+ * dh_book_manager_new:
+ *
+ * Create a new #DhBookManager object.
+ *
+ * Returns: a new #DhBookManager object
+ */
 DhBookManager *
 dh_book_manager_new (void)
 {
diff --git a/src/dh-book-tree.c b/src/dh-book-tree.c
index 0401999..9c05e47 100644
--- a/src/dh-book-tree.c
+++ b/src/dh-book-tree.c
@@ -692,7 +692,11 @@ dh_book_tree_class_init (DhBookTreeClass *klass)
                                                               DH_TYPE_BOOK_MANAGER,
                                                               G_PARAM_READWRITE |
                                                               G_PARAM_CONSTRUCT_ONLY));
-
+        /**
+         * DhBookTree::link-selected:
+         * @tree: a #DhBookTree object
+         * @link: (type DhLink): the selected #DhLink
+         */
         signals[LINK_SELECTED] =
                 g_signal_new ("link-selected",
                               G_TYPE_FROM_CLASS (klass),
@@ -749,6 +753,14 @@ dh_book_tree_init (DhBookTree *tree)
         book_tree_setup_selection (tree);
 }
 
+/**
+ * dh_book_tree_new:
+ * @book_manager: the parent #DhBookManager
+ *
+ * Create a new #DhBookManager object.
+ *
+ * Returns: a new #DhBookManager object
+ */
 GtkWidget *
 dh_book_tree_new (DhBookManager *book_manager)
 {
@@ -788,6 +800,13 @@ book_tree_find_uri_foreach (GtkTreeModel *model,
         return data->found;
 }
 
+/**
+ * dh_book_tree_select_uri:
+ * @tree: a #DhBookTree object
+ * @uri: the uri to select
+ *
+ * Select the given @uri.
+ */
 void
 dh_book_tree_select_uri (DhBookTree  *tree,
                          const gchar *uri)
@@ -837,6 +856,14 @@ dh_book_tree_select_uri (DhBookTree  *tree,
         gtk_tree_path_free (data.path);
 }
 
+/**
+ * dh_book_tree_get_selected_book:
+ * @tree: a #DhBookTree object
+ *
+ * Get the link pointing to the selected book.
+ *
+ * Returns: (nullable) (transfer full): the selected book link
+ */
 DhLink *
 dh_book_tree_get_selected_book (DhBookTree *tree)
 {
diff --git a/src/dh-book-tree.h b/src/dh-book-tree.h
index 1c13b60..e4cc4d2 100644
--- a/src/dh-book-tree.h
+++ b/src/dh-book-tree.h
@@ -44,7 +44,7 @@ struct _DhBookTreeClass {
 
 GType        dh_book_tree_get_type          (void) G_GNUC_CONST;
 GtkWidget *  dh_book_tree_new               (DhBookManager *book_manager);
-void         dh_book_tree_select_uri        (DhBookTree    *book_tree,
+void         dh_book_tree_select_uri        (DhBookTree    *tree,
                                              const gchar   *uri);
 DhLink      *dh_book_tree_get_selected_book (DhBookTree    *tree);
 
diff --git a/src/dh-book.c b/src/dh-book.c
index b0dc663..553a22b 100644
--- a/src/dh-book.c
+++ b/src/dh-book.c
@@ -144,6 +144,10 @@ dh_book_class_init (DhBookClass *klass)
         object_class->dispose = dh_book_dispose;
         object_class->finalize = dh_book_finalize;
 
+        /**
+         * DhBook::enabled:
+         * @book: the book on which the signal is emitted
+         */
         signals[BOOK_ENABLED] =
                 g_signal_new ("enabled",
                               G_TYPE_FROM_CLASS (klass),
@@ -154,6 +158,10 @@ dh_book_class_init (DhBookClass *klass)
                               G_TYPE_NONE,
                               0);
 
+        /**
+         * DhBook::disabled:
+         * @book: the book on which the signal is emitted
+         */
         signals[BOOK_DISABLED] =
                 g_signal_new ("disabled",
                               G_TYPE_FROM_CLASS (klass),
@@ -164,7 +172,10 @@ dh_book_class_init (DhBookClass *klass)
                               G_TYPE_NONE,
                               0);
 
-
+        /**
+         * DhBook::updated:
+         * @book: the book on which the signal is emitted
+         */
         signals[BOOK_UPDATED] =
                 g_signal_new ("updated",
                               G_TYPE_FROM_CLASS (klass),
@@ -175,6 +186,10 @@ dh_book_class_init (DhBookClass *klass)
                               G_TYPE_NONE,
                               0);
 
+        /**
+         * DhBook::deleted:
+         * @book: the book on which the signal is emitted
+         */
         signals[BOOK_DELETED] =
                 g_signal_new ("deleted",
                               G_TYPE_FROM_CLASS (klass),
@@ -210,6 +225,14 @@ unref_node_link (GNode    *node,
         dh_link_unref (node->data);
 }
 
+/**
+ * dh_book_new:
+ * @book_path: the path of the book
+ *
+ * Create a new #DhBook object.
+ *
+ * Returns: a new #DhBook object
+ */
 DhBook *
 dh_book_new (const gchar *book_path)
 {
@@ -355,6 +378,14 @@ book_monitor_event_cb (GFileMonitor      *file_monitor,
         }
 }
 
+/**
+ * dh_book_get_keywords:
+ * @book: a #DhBook object
+ *
+ * Get the #GList of keywords associated with the book.
+ *
+ * Returns: (element-type utf8) (transfer none) (nullable): the keywords associated with the book
+ */
 GList *
 dh_book_get_keywords (DhBook *book)
 {
@@ -367,6 +398,14 @@ dh_book_get_keywords (DhBook *book)
         return priv->enabled ? priv->keywords : NULL;
 }
 
+/**
+ * dh_book_get_completions:
+ * @book: a #DhBook object
+ *
+ * Get the #GList of completions associated with the book.
+ *
+ * Returns: (element-type utf8) (transfer full) (nullable): the completions associated with the book
+ */
 GList *
 dh_book_get_completions (DhBook *book)
 {
@@ -406,6 +445,14 @@ dh_book_get_completions (DhBook *book)
         return priv->completions;
 }
 
+/**
+ * dh_book_get_tree:
+ * @book: a #DhBook object
+ *
+ * Get the #GNode representing the book tree.
+ *
+ * Returns: (transfer none) (nullable): the book tree
+ */
 GNode *
 dh_book_get_tree (DhBook *book)
 {
@@ -418,6 +465,14 @@ dh_book_get_tree (DhBook *book)
         return priv->enabled ? priv->tree : NULL;
 }
 
+/**
+ * dh_book_get_name:
+ * @book: a #DhBook object
+ *
+ * Get the book name.
+ *
+ * Returns: the book name
+ */
 const gchar *
 dh_book_get_name (DhBook *book)
 {
@@ -430,6 +485,14 @@ dh_book_get_name (DhBook *book)
         return priv->name;
 }
 
+/**
+ * dh_book_get_title:
+ * @book: a #DhBook object
+ *
+ * Get the book title.
+ *
+ * Returns: the book title
+ */
 const gchar *
 dh_book_get_title (DhBook *book)
 {
@@ -442,6 +505,14 @@ dh_book_get_title (DhBook *book)
         return priv->title;
 }
 
+/**
+ * dh_book_get_language:
+ * @book: a #DhBook object
+ *
+ * Get the book language.
+ *
+ * Returns: the book language
+ */
 const gchar *
 dh_book_get_language (DhBook *book)
 {
@@ -454,6 +525,14 @@ dh_book_get_language (DhBook *book)
         return priv->language;
 }
 
+/**
+ * dh_book_get_path:
+ * @book: a #DhBook object
+ *
+ * Get the book path.
+ *
+ * Returns: the book path
+ */
 const gchar *
 dh_book_get_path (DhBook *book)
 {
@@ -466,6 +545,14 @@ dh_book_get_path (DhBook *book)
         return priv->path;
 }
 
+/**
+ * dh_book_get_enabled:
+ * @book: a #DhBook object
+ *
+ * Get the current state of the book.
+ *
+ * Returns: %TRUE if the book is enabled
+ */
 gboolean
 dh_book_get_enabled (DhBook *book)
 {
@@ -478,6 +565,13 @@ dh_book_get_enabled (DhBook *book)
         return priv->enabled;
 }
 
+/**
+ * dh_book_set_enabled:
+ * @book: a #DhBook object
+ * @enabled: %TRUE to enable the book
+ *
+ * Enable or disable completely the book.
+ */
 void
 dh_book_set_enabled (DhBook   *book,
                      gboolean  enabled)
@@ -495,6 +589,15 @@ dh_book_set_enabled (DhBook   *book,
         }
 }
 
+/**
+ * dh_book_cmp_by_path:
+ * @a: a #DhBook object
+ * @b: a second #DhBook object
+ *
+ * Compare the #DhBook @a and @b by their paths.
+ *
+ * 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,
                      DhBook *b)
@@ -511,6 +614,15 @@ dh_book_cmp_by_path (DhBook *a,
         return g_strcmp0 (priv_a->path, priv_b->path);
 }
 
+/**
+ * dh_book_cmp_by_path_str:
+ * @a: a #DhBook object
+ * @b_path: a path to a book
+ *
+ * Compare the path 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.
+ */
 gint
 dh_book_cmp_by_path_str (DhBook      *a,
                          const gchar *b_path)
@@ -525,6 +637,15 @@ dh_book_cmp_by_path_str (DhBook      *a,
         return g_strcmp0 (priv_a->path, b_path);
 }
 
+/**
+ * dh_book_cmp_by_name:
+ * @a: a #DhBook object
+ * @b: a second #DhBook object
+ *
+ * Compare the #DhBook @a and @b by their name.
+ *
+ * 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,
                      DhBook *b)
@@ -544,6 +665,15 @@ dh_book_cmp_by_name (DhBook *a,
         return g_ascii_strcasecmp (priv_a->name, priv_b->name);
 }
 
+/**
+ * dh_book_cmp_by_name_str:
+ * @a: a #DhBook object
+ * @b_name: a path to a book
+ *
+ * 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.
+ */
 gint
 dh_book_cmp_by_name_str (DhBook      *a,
                          const gchar *b_name)
@@ -561,6 +691,15 @@ dh_book_cmp_by_name_str (DhBook      *a,
         return g_ascii_strcasecmp (priv_a->name, b_name);
 }
 
+/**
+ * dh_book_cmp_by_title:
+ * @a: a #DhBook object
+ * @b: a second #DhBook object
+ *
+ * Compare the #DhBook @a and @b by their title.
+ *
+ * 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,
                       DhBook *b)
diff --git a/src/dh-keyword-model.c b/src/dh-keyword-model.c
index 0bf9f6e..f9d3840 100644
--- a/src/dh-keyword-model.c
+++ b/src/dh-keyword-model.c
@@ -355,12 +355,26 @@ dh_keyword_model_tree_model_init (GtkTreeModelIface *iface)
         iface->iter_parent     = keyword_model_iter_parent;
 }
 
+/**
+ * dh_keyword_model_new:
+ *
+ * Create a new #DhKeywordModel object.
+ *
+ * Returns: a new #DhKeywordModel object
+ */
 DhKeywordModel *
 dh_keyword_model_new (void)
 {
         return g_object_new (DH_TYPE_KEYWORD_MODEL, NULL);
 }
 
+/**
+ * dh_keyword_model_set_words:
+ * @model: a #DhKeywordModel object
+ * @book_manager: a #DhBookManager to analyze
+ *
+ * Set the #DhBookManager object on which words are analyzed.
+ */
 void
 dh_keyword_model_set_words (DhKeywordModel *model,
                             DhBookManager  *book_manager)
@@ -965,6 +979,18 @@ set_keywords_list (DhKeywordModel *model,
         }
 }
 
+/**
+ * dh_keyword_model_filter:
+ * @model: a #DhKeywordModel object
+ * @search_string: a search query
+ * @book_id: (nullable): the id of a specific book or %NULL for all books
+ * @language: (nullable): the name of a language or %NULL for all languages
+ *
+ * Find the book matching the given criteria.
+ *
+ * Returns: (nullable) (transfer none): the corresponding #DhLink or %NULL if
+ * no link corresponding to the criteria is found
+ */
 DhLink *
 dh_keyword_model_filter (DhKeywordModel *model,
                          const gchar    *search_string,
diff --git a/src/dh-keyword-model.h b/src/dh-keyword-model.h
index fc18e33..07f1949 100644
--- a/src/dh-keyword-model.h
+++ b/src/dh-keyword-model.h
@@ -58,7 +58,7 @@ DhKeywordModel *dh_keyword_model_new       (void);
 void            dh_keyword_model_set_words (DhKeywordModel *model,
                                             DhBookManager  *book_manager);
 DhLink *        dh_keyword_model_filter    (DhKeywordModel *model,
-                                            const gchar    *string,
+                                            const gchar    *search_string,
                                             const gchar    *book_id,
                                             const gchar    *language);
 
diff --git a/src/dh-language.c b/src/dh-language.c
index 28f6f09..b2e0f8d 100644
--- a/src/dh-language.c
+++ b/src/dh-language.c
@@ -27,6 +27,12 @@ struct _DhLanguage {
         gint   n_books_enabled;
 };
 
+/**
+ * dh_language_free:
+ * @language: a #DhLanguage object
+ *
+ * Free memory associated with the language.
+ */
 void
 dh_language_free (DhLanguage *language)
 {
@@ -34,6 +40,14 @@ dh_language_free (DhLanguage *language)
         g_slice_free (DhLanguage, language);
 }
 
+/**
+ * dh_language_new:
+ * @name: the name of the language
+ *
+ * Create a new #DhLanguage object.
+ *
+ * Returns: a new #DhLanguage object
+ */
 DhLanguage *
 dh_language_new (const gchar *name)
 {
@@ -47,6 +61,16 @@ dh_language_new (const gchar *name)
         return language;
 }
 
+/**
+ * dh_language_compare:
+ * @language_a: a #DhLanguage object
+ * @language_b: the #DhLanguage object to compare with
+ *
+ * Compares the name of @language_a with the name @language_b.
+ *
+ * Returns: an integer less than, equal to, or greater than zero, if the name
+ * of @language_a is <, == or > than the name of @language_b
+ */
 gint
 dh_language_compare (const DhLanguage *language_a,
                      const DhLanguage *language_b)
@@ -57,6 +81,16 @@ dh_language_compare (const DhLanguage *language_a,
         return strcmp (language_a->name, language_b->name);
 }
 
+/**
+ * dh_language_compare_by_name:
+ * @language_a: a #DhLanguage object
+ * @language_name_b: the language name to compare with
+ *
+ * Compares the name of @language_a with @language_name_b.
+ *
+ * Returns: an integer less than, equal to, or greater than zero, if the name
+ * of @language_a is <, == or > than @language_name_b
+ */
 gint
 dh_language_compare_by_name (const DhLanguage *language_a,
                              const gchar      *language_name_b)
@@ -67,6 +101,14 @@ dh_language_compare_by_name (const DhLanguage *language_a,
         return strcmp (language_a->name, language_name_b);
 }
 
+/**
+ * dh_language_get_name:
+ * @language: a #DhLanguage object
+ *
+ * Get the language name.
+ *
+ * Returns: The name of the language
+ */
 const gchar *
 dh_language_get_name (DhLanguage *language)
 {
@@ -75,7 +117,14 @@ dh_language_get_name (DhLanguage *language)
         return language->name;
 }
 
-
+/**
+ * dh_language_get_n_books_enabled:
+ * @language: a #DhLanguage object
+ *
+ * Get the number of enabled books
+ *
+ * Returns: The number of enabled books
+ */
 gint
 dh_language_get_n_books_enabled (DhLanguage *language)
 {
@@ -84,6 +133,12 @@ dh_language_get_n_books_enabled (DhLanguage *language)
         return language->n_books_enabled;
 }
 
+/**
+ * dh_language_inc_n_books_enabled:
+ * @language: a #DhLanguage object
+ *
+ * Increase the number of enabled books for this language.
+ */
 void
 dh_language_inc_n_books_enabled (DhLanguage *language)
 {
@@ -92,6 +147,14 @@ dh_language_inc_n_books_enabled (DhLanguage *language)
         language->n_books_enabled++;
 }
 
+/**
+ * dh_language_dec_n_books_enabled:
+ * @language: a #DhLanguage object
+ *
+ * Decrease the number of enabled books for this language.
+ *
+ * Returns: %TRUE if the counter is decreased to zero, %FALSE otherwise.
+ */
 gboolean
 dh_language_dec_n_books_enabled (DhLanguage *language)
 {
diff --git a/src/dh-link.c b/src/dh-link.c
index 4337eda..c07a319 100644
--- a/src/dh-link.c
+++ b/src/dh-link.c
@@ -65,6 +65,23 @@ link_free (DhLink *link)
         g_slice_free (DhLink, link);
 }
 
+/**
+ * dh_link_new:
+ * @type: the type of the content the link is pointing to
+ * @base: the base path of the link
+ * @id: the id of the link
+ * @name: the name of the link
+ * @book: (nullable): the link to the associated book or %NULL
+ * @page: (nullable): the link to the associated page or %NULL
+ * @filename: the filename of the link
+ *
+ * Create a new #DhLink object.
+ *
+ * If type is one of #DH_LINK_TYPE_BOOK or #DH_LINK_TYPE_PAGE then the @book and
+ * @page links have to be provided.
+ *
+ * Returns: a new #DhLink object
+ */
 DhLink *
 dh_link_new (DhLinkType   type,
              const gchar *base,
@@ -111,6 +128,15 @@ dh_link_new (DhLinkType   type,
         return link;
 }
 
+/**
+ * dh_link_compare:
+ * @a: (type DhLink): a #DhLink object
+ * @b: (type DhLink): the #DhLink to compare
+ *
+ * Compare the link @a and @b.
+ *
+ * Returns: an integer less than, equal to, or greater than zero, if @a is <, == or > than @b.
+ */
 gint
 dh_link_compare (gconstpointer a,
                  gconstpointer b)
@@ -155,6 +181,14 @@ dh_link_compare (gconstpointer a,
         return diff;
 }
 
+/**
+ * dh_link_ref:
+ * @link: a #DhLink object
+ *
+ * Increase the reference count of @link.
+ *
+ * Returns: (transfer full): the @link object
+ */
 DhLink *
 dh_link_ref (DhLink *link)
 {
@@ -165,6 +199,12 @@ dh_link_ref (DhLink *link)
         return link;
 }
 
+/**
+ * dh_link_unref:
+ * @link: a #DhLink object
+ *
+ * Decrease the reference count of @link.
+ */
 void
 dh_link_unref (DhLink *link)
 {
@@ -176,12 +216,28 @@ dh_link_unref (DhLink *link)
         }
 }
 
+/**
+ * dh_link_get_name:
+ * @link: a #DhLink object
+ *
+ * Get the name of the link.
+ *
+ * Returns: the name of the link
+ */
 const gchar *
 dh_link_get_name (DhLink *link)
 {
         return link->name;
 }
 
+/**
+ * dh_link_get_book_name:
+ * @link: a #DhLink object
+ *
+ * Get the book name the link is pointing to.
+ *
+ * Returns: the book name the link is pointing to
+ */
 const gchar *
 dh_link_get_book_name (DhLink *link)
 {
@@ -192,6 +248,14 @@ dh_link_get_book_name (DhLink *link)
         return "";
 }
 
+/**
+ * dh_link_get_page_name:
+ * @link: a #DhLink object
+ *
+ * Get the page name the link is pointing to.
+ *
+ * Returns: the page name the link is pointing to
+ */
 const gchar *
 dh_link_get_page_name (DhLink *link)
 {
@@ -202,6 +266,14 @@ dh_link_get_page_name (DhLink *link)
         return "";
 }
 
+/**
+ * dh_link_get_file_name:
+ * @link: a #DhLink object
+ *
+ * Get the file name of the link.
+ *
+ * Returns: the file name of the link
+ */
 const gchar *
 dh_link_get_file_name (DhLink *link)
 {
@@ -215,6 +287,14 @@ dh_link_get_file_name (DhLink *link)
         return "";
 }
 
+/**
+ * dh_link_get_book_id:
+ * @link: a #DhLink object
+ *
+ * Get the book id the link is pointing to.
+ *
+ * Returns: the book id the link is pointing to
+ */
 const gchar *
 dh_link_get_book_id (DhLink *link)
 {
@@ -229,6 +309,14 @@ dh_link_get_book_id (DhLink *link)
         return "";
 }
 
+/**
+ * dh_link_get_uri:
+ * @link: a #DhLink object
+ *
+ * Get the uri of the link.
+ *
+ * Returns: the uri of the link
+ */
 gchar *
 dh_link_get_uri (DhLink *link)
 {
@@ -261,18 +349,41 @@ dh_link_get_uri (DhLink *link)
         return uri;
 }
 
+/**
+ * dh_link_get_link_type:
+ * @link: a #DhLink object
+ *
+ * Get the type of the link.
+ *
+ * Returns: the type of the link
+ */
 DhLinkType
 dh_link_get_link_type (DhLink *link)
 {
         return link->type;
 }
 
+/**
+ * dh_link_get_flags:
+ * @link: a #DhLink object
+ *
+ * Get the flags of the link.
+ *
+ * Returns: the flags of the link
+ */
 DhLinkFlags
 dh_link_get_flags (DhLink *link)
 {
         return link->flags;
 }
 
+/**
+ * dh_link_set_flags:
+ * @link: a #DhLink object
+ * @flags: the new flags of the link
+ *
+ * Set the flags of the link.
+ */
 void
 dh_link_set_flags (DhLink      *link,
                    DhLinkFlags  flags)
@@ -280,6 +391,14 @@ dh_link_set_flags (DhLink      *link,
         link->flags = flags;
 }
 
+/**
+ * dh_link_get_type_as_string:
+ * @link: a #DhLink object
+ *
+ * Get the link type name.
+ *
+ * Returns: the link type name translated in the current language
+ */
 const gchar *
 dh_link_get_type_as_string (DhLink *link)
 {
diff --git a/src/dh-sidebar.c b/src/dh-sidebar.c
index f75677a..c3fc5f1 100644
--- a/src/dh-sidebar.c
+++ b/src/dh-sidebar.c
@@ -338,8 +338,13 @@ sidebar_entry_insert_text_cb (GtkEntry    *entry,
                         g_idle_add ((GSourceFunc) sidebar_complete_idle_cb, sidebar);
 }
 
-/******************************************************************************/
-
+/**
+ * dh_sidebar_set_search_string:
+ * @sidebar: a #DhSidebar object
+ * @str: the string to seach
+ *
+ * Set the search string to @str.
+ */
 void
 dh_sidebar_set_search_string (DhSidebar   *sidebar,
                               const gchar *str)
@@ -355,8 +360,12 @@ dh_sidebar_set_search_string (DhSidebar   *sidebar,
         gtk_editable_select_region (GTK_EDITABLE (priv->entry), -1, -1);
 }
 
-/******************************************************************************/
-
+/**
+ * dh_sidebar_set_search_focus:
+ * @sidebar: a #DhSidebar object
+ *
+ * Give the focus to the search entry.
+ */
 void
 dh_sidebar_set_search_focus (DhSidebar *sidebar)
 {
@@ -365,8 +374,6 @@ dh_sidebar_set_search_focus (DhSidebar *sidebar)
         gtk_widget_grab_focus (GTK_WIDGET (priv->entry));
 }
 
-/******************************************************************************/
-
 static void
 hitlist_cell_data_func (GtkTreeViewColumn *tree_column,
                         GtkCellRenderer   *cell,
@@ -419,8 +426,6 @@ hitlist_cell_data_func (GtkTreeViewColumn *tree_column,
         g_free (name);
 }
 
-/******************************************************************************/
-
 static void
 sidebar_book_tree_link_selected_cb (DhBookTree *book_tree,
                                     DhLink     *link,
@@ -429,6 +434,14 @@ sidebar_book_tree_link_selected_cb (DhBookTree *book_tree,
         g_signal_emit (sidebar, signals[LINK_SELECTED], 0, link);
 }
 
+/**
+ * dh_sidebar_get_selected_book:
+ * @sidebar: a #DhSidebar object
+ *
+ * Get the link pointing to the selected book.
+ *
+ * Returns: (nullable) (transfer full): the selected book link
+ */
 DhLink *
 dh_sidebar_get_selected_book (DhSidebar *sidebar)
 {
@@ -441,6 +454,13 @@ dh_sidebar_get_selected_book (DhSidebar *sidebar)
         return dh_book_tree_get_selected_book (priv->book_tree);
 }
 
+/**
+ * dh_sidebar_select_uri:
+ * @sidebar: a #DhSidebar object
+ * @uri: the uri to select
+ *
+ * Select the given @uri.
+ */
 void
 dh_sidebar_select_uri (DhSidebar   *sidebar,
                        const gchar *uri)
@@ -454,8 +474,14 @@ dh_sidebar_select_uri (DhSidebar   *sidebar,
         dh_book_tree_select_uri (priv->book_tree, uri);
 }
 
-/******************************************************************************/
-
+/**
+ * dh_sidebar_new:
+ * @book_manager: the book manager
+ *
+ * Create a new #DhSidebar object.
+ *
+ * Returns: a new #DhSidebar object
+ */
 GtkWidget *
 dh_sidebar_new (DhBookManager *book_manager)
 {
@@ -676,6 +702,11 @@ dh_sidebar_class_init (DhSidebarClass *klass)
                                                               G_PARAM_READWRITE |
                                                               G_PARAM_CONSTRUCT_ONLY));
 
+        /**
+         * DhSidebar::link-selected:
+         * @sidebar: a #DhSidebar object
+         * @link: the selected #DhLink
+         */
         signals[LINK_SELECTED] =
                 g_signal_new ("link_selected",
                               G_TYPE_FROM_CLASS (klass),
diff --git a/src/dh-sidebar.h b/src/dh-sidebar.h
index fb0bcc5..e52706b 100644
--- a/src/dh-sidebar.h
+++ b/src/dh-sidebar.h
@@ -56,12 +56,12 @@ struct _DhSidebarClass {
 GType      dh_sidebar_get_type (void);
 GtkWidget *dh_sidebar_new      (DhBookManager *book_manager);
 
-DhLink    *dh_sidebar_get_selected_book (DhSidebar *self);
-void       dh_sidebar_select_uri        (DhSidebar   *self,
+DhLink    *dh_sidebar_get_selected_book (DhSidebar *sidebar);
+void       dh_sidebar_select_uri        (DhSidebar   *sidebar,
                                          const gchar *uri);
-void       dh_sidebar_set_search_string (DhSidebar   *self,
+void       dh_sidebar_set_search_string (DhSidebar   *sidebar,
                                          const gchar *str);
-void       dh_sidebar_set_search_focus  (DhSidebar   *self);
+void       dh_sidebar_set_search_focus  (DhSidebar   *sidebar);
 
 G_END_DECLS
 
diff --git a/src/dh-window.c b/src/dh-window.c
index d72140a..5d10030 100644
--- a/src/dh-window.c
+++ b/src/dh-window.c
@@ -733,6 +733,12 @@ dh_window_class_init (DhWindowClass *klass)
 
         klass->open_link = dh_window_open_link;
 
+        /**
+         * DhWindow::open-link:
+         * @window: a #DhWindow object
+         * @location: the location of the link
+         * @flags: a #DhOpenLinkFlags
+         */
         signals[OPEN_LINK] =
                 g_signal_new ("open-link",
                               G_TYPE_FROM_CLASS (klass),
@@ -1550,6 +1556,14 @@ window_tab_set_title (DhWindow      *window,
         }
 }
 
+/**
+ * dh_window_new:
+ * @application: the #DhApp owning this window
+ *
+ * Create a new #DhWindow object.
+ *
+ * Returns: a new #DhWindow object
+ */
 GtkWidget *
 dh_window_new (DhApp *application)
 {
@@ -1575,6 +1589,13 @@ dh_window_new (DhApp *application)
         return GTK_WIDGET (window);
 }
 
+/**
+ * dh_window_search:
+ * @window: a #DhWindow object
+ * @str: the string to search
+ *
+ * Search for @str in the current window.
+ */
 void
 dh_window_search (DhWindow    *window,
                   const gchar *str)
@@ -1588,7 +1609,15 @@ dh_window_search (DhWindow    *window,
         dh_sidebar_set_search_string (priv->sidebar, str);
 }
 
-/* Only call this with a URI that is known to be in the docs. */
+/*< private >
+ * _dh_window_display_uri:
+ * @window: a #DhWindow object
+ * @uri: the uri to display
+ *
+ * Open the @uri in the current window.
+ *
+ * Only call this with a URI that is known to be in the docs.
+ */
 void
 _dh_window_display_uri (DhWindow    *window,
                         const gchar *uri)



[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]