[devhelp/wip/tintou/more-annotations] Improve the documentation coverage
- From: Corentin Noël <corentinnoel src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [devhelp/wip/tintou/more-annotations] Improve the documentation coverage
- Date: Sun, 30 Oct 2016 10:40:48 +0000 (UTC)
commit 85950078bbc342283f13019338dec70546aa499b
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..394118c 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: (type DhAssistantView) (transfer full): 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..39c014f 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: (type DhAssistant) (transfer full): 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..b2267d9 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: (type DhBookTree) (transfer full): 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..da20082 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: (type DhWindow) (transfer full): 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]
