[gnome-todo/wip/gbsneto/plugins] project: fix documentation



commit e1fce7e6f94d57e91921fc14fc242ede827a686f
Author: Georges Basile Stavracas Neto <georges stavracas gmail com>
Date:   Fri Jan 15 22:16:56 2016 -0200

    project: fix documentation
    
    I'm paying my sins today.

 src/gtd-manager-protected.h         |    2 +
 src/gtd-manager.c                   |   53 +++++++++--------
 src/gtd-manager.h                   |    2 -
 src/gtd-object.c                    |    8 +-
 src/gtd-task-list-view.c            |   15 +----
 src/gtd-task-list.c                 |   28 ++++++---
 src/gtd-task.c                      |   49 ++++++++++------
 src/gtd-task.h                      |    2 +-
 src/gtd-window.c                    |    6 --
 src/interfaces/gtd-activatable.c    |   34 +++++++++++
 src/interfaces/gtd-panel.c          |   38 +++++++++++++
 src/interfaces/gtd-provider.c       |  104 +++++++++++++++++++++++++++++++++-
 src/notification/gtd-notification.c |   34 ++++++-----
 src/notification/gtd-notification.h |    8 +++
 src/plugin/gtd-plugin-dialog.c      |    1 +
 15 files changed, 285 insertions(+), 99 deletions(-)
---
diff --git a/src/gtd-manager-protected.h b/src/gtd-manager-protected.h
index c4346a9..546a6da 100644
--- a/src/gtd-manager-protected.h
+++ b/src/gtd-manager-protected.h
@@ -25,6 +25,8 @@ G_BEGIN_DECLS
 
 void                 gtd_manager_load_plugins                    (GtdManager         *manager);
 
+GtdPluginManager*    gtd_manager_get_plugin_manager              (GtdManager         *manager);
+
 G_END_DECLS
 
 #endif /* GTD_MANAGER_PROTECTED_H */
diff --git a/src/gtd-manager.c b/src/gtd-manager.c
index e53efd5..d66899c 100644
--- a/src/gtd-manager.c
+++ b/src/gtd-manager.c
@@ -166,6 +166,8 @@ gtd_manager_class_init (GtdManagerClass *klass)
 
   /**
    * GtdManager::list-added:
+   * @manager: a #GtdManager
+   * @list: a #GtdTaskList
    *
    * The ::list-added signal is emmited after a #GtdTaskList
    * is connected.
@@ -181,8 +183,10 @@ gtd_manager_class_init (GtdManagerClass *klass)
                                       1,
                                       GTD_TYPE_TASK_LIST);
 
-/**
+  /**
    * GtdManager::list-changed:
+   * @manager: a #GtdManager
+   * @list: a #GtdTaskList
    *
    * The ::list-changed signal is emmited after a #GtdTaskList
    * has any of it's properties changed.
@@ -200,6 +204,8 @@ gtd_manager_class_init (GtdManagerClass *klass)
 
   /**
    * GtdManager::list-removed:
+   * @manager: a #GtdManager
+   * @list: a #GtdTaskList
    *
    * The ::list-removed signal is emmited after a #GtdTaskList
    * is disconnected.
@@ -217,10 +223,12 @@ gtd_manager_class_init (GtdManagerClass *klass)
 
   /**
    * GtdManager::show-error-message:
+   * @manager: a #GtdManager
+   * @primary_text: the primary message
+   * @secondary_text: the detailed explanation of the error
    *
    * Notifies about errors, and sends the error message for widgets
    * to display.
-   *
    */
   signals[SHOW_ERROR_MESSAGE] = g_signal_new ("show-error-message",
                                               GTD_TYPE_MANAGER,
@@ -236,6 +244,8 @@ gtd_manager_class_init (GtdManagerClass *klass)
 
   /**
    * GtdManager::panel-added:
+   * @manager: a #GtdManager
+   * @panel: a #GtdPanel
    *
    * The ::panel-added signal is emmited after a #GtdPanel
    * is added.
@@ -253,6 +263,8 @@ gtd_manager_class_init (GtdManagerClass *klass)
 
   /**
    * GtdManager::panel-removed:
+   * @manager: a #GtdManager
+   * @panel: a #GtdPanel
    *
    * The ::panel-removed signal is emmited after a #GtdPanel
    * is removed from the list.
@@ -270,6 +282,8 @@ gtd_manager_class_init (GtdManagerClass *klass)
 
   /**
    * GtdManager::provider-added:
+   * @manager: a #GtdManager
+   * @provider: a #GtdProvider
    *
    * The ::provider-added signal is emmited after a #GtdProvider
    * is added.
@@ -287,6 +301,8 @@ gtd_manager_class_init (GtdManagerClass *klass)
 
   /**
    * GtdManager::provider-removed:
+   * @manager: a #GtdManager
+   * @provider: a #GtdProvider
    *
    * The ::provider-removed signal is emmited after a #GtdProvider
    * is removed from the list.
@@ -480,8 +496,6 @@ gtd_manager_new (void)
  * @task: a #GtdTask
  *
  * Ask for @task's parent list source to create @task.
- *
- * Returns:
  */
 void
 gtd_manager_create_task (GtdManager *manager,
@@ -505,8 +519,6 @@ gtd_manager_create_task (GtdManager *manager,
  * @task: a #GtdTask
  *
  * Ask for @task's parent list source to remove @task.
- *
- * Returns:
  */
 void
 gtd_manager_remove_task (GtdManager *manager,
@@ -530,8 +542,6 @@ gtd_manager_remove_task (GtdManager *manager,
  * @task: a #GtdTask
  *
  * Ask for @task's parent list source to update @task.
- *
- * Returns:
  */
 void
 gtd_manager_update_task (GtdManager *manager,
@@ -551,11 +561,10 @@ gtd_manager_update_task (GtdManager *manager,
 
 /**
  * gtd_manager_create_task_list:
- *
+ * @manager: a #GtdManager
+ * @list: a #GtdTaskList
  *
  * Creates a new task list at the given source.
- *
- * Returns:
  */
 void
 gtd_manager_create_task_list (GtdManager  *manager,
@@ -577,8 +586,6 @@ gtd_manager_create_task_list (GtdManager  *manager,
  * @list: a #GtdTaskList
  *
  * Deletes @list from the registry.
- *
- * Returns:
  */
 void
 gtd_manager_remove_task_list (GtdManager  *manager,
@@ -605,8 +612,6 @@ gtd_manager_remove_task_list (GtdManager  *manager,
  * @list: a #GtdTaskList
  *
  * Save or create @list.
- *
- * Returns:
  */
 void
 gtd_manager_save_task_list (GtdManager  *manager,
@@ -628,7 +633,7 @@ gtd_manager_save_task_list (GtdManager  *manager,
  *
  * Retrieves the list of #GtdTaskList already loaded.
  *
- * Returns: (transfer full): a newly allocated list of #GtdTaskList, or %NULL if none.
+ * Returns: (transfer container) (element-type #GtdTaskList): a newly allocated list of #GtdTaskList, or 
%NULL if none.
  */
 GList*
 gtd_manager_get_task_lists (GtdManager *manager)
@@ -639,11 +644,12 @@ gtd_manager_get_task_lists (GtdManager *manager)
 }
 
 /**
- * gtd_manager_get_storage_locations:
+ * gtd_manager_get_providers:
+ * @manager: a #GtdManager
  *
- * Retrieves the list of available #GtdStorage.
+ * Retrieves the list of available #GtdProvider.
  *
- * Returns: (transfer full): (type #GtdStorage): a newly allocated #GList of
+ * Returns: (transfer container) (element-type #GtdProvider): a newly allocated #GList of
  * #GtdStorage. Free with @g_list_free after use.
  */
 GList*
@@ -656,11 +662,12 @@ gtd_manager_get_providers (GtdManager *manager)
 
 /**
  * gtd_manager_get_panels:
+ * @manager: a #GtdManager
  *
  * Retrieves the list of currently loaded #GtdPanel
  * instances.
  *
- * Returns: (transger full): a #GList of #GtdPanel
+ * Returns: (transfer container) (element-type #GtdPanel): a #GList of #GtdPanel
  */
 GList*
 gtd_manager_get_panels (GtdManager *manager)
@@ -689,11 +696,9 @@ gtd_manager_get_default_provider (GtdManager *manager)
 /**
  * gtd_manager_set_default_storage:
  * @manager: a #GtdManager
- * @default_storage: the default storage location.
+ * @default_storage: (nullable): the default storage location.
  *
  * Sets the default storage location id.
- *
- * Returns:
  */
 void
 gtd_manager_set_default_provider (GtdManager  *manager,
@@ -753,8 +758,6 @@ gtd_manager_get_is_first_run (GtdManager *manager)
  * @is_first_run: %TRUE to make it first run, %FALSE otherwise.
  *
  * Sets the 'first-run' setting.
- *
- * Returns:
  */
 void
 gtd_manager_set_is_first_run (GtdManager *manager,
diff --git a/src/gtd-manager.h b/src/gtd-manager.h
index 38c0ff9..d2136aa 100644
--- a/src/gtd-manager.h
+++ b/src/gtd-manager.h
@@ -77,8 +77,6 @@ void                    gtd_manager_emit_error_message    (GtdManager
                                                            const gchar          *primary_message,
                                                            const gchar          *secondary_message);
 
-GtdPluginManager*       gtd_manager_get_plugin_manager    (GtdManager           *manager);
-
 G_END_DECLS
 
 #endif /* GTD_MANAGER_H */
diff --git a/src/gtd-object.c b/src/gtd-object.c
index fc9c93b..33603d5 100644
--- a/src/gtd-object.c
+++ b/src/gtd-object.c
@@ -215,11 +215,11 @@ gtd_object_get_uid (GtdObject *object)
 
 /**
  * gtd_object_set_uid:
+ * @object: a #GtdObject
+ * @uid: the unique identifier of @object
  *
  * Sets the unique identifier of @object to @uid. Only
  * a #GtdBackend should do it.
- *
- * Returns:
  */
 void
 gtd_object_set_uid (GtdObject   *object,
@@ -257,10 +257,10 @@ gtd_object_get_ready (GtdObject *object)
 
 /**
  * gtd_object_set_ready:
+ * @object: a #GtdObject
+ * @ready: whether @object is ready or not
  *
  * Sets the GtdObject::ready property to @ready.
- *
- * Returns:
  */
 void
 gtd_object_set_ready (GtdObject *object,
diff --git a/src/gtd-task-list-view.c b/src/gtd-task-list-view.c
index 3354312..4adfaf0 100644
--- a/src/gtd-task-list-view.c
+++ b/src/gtd-task-list-view.c
@@ -839,7 +839,7 @@ gtd_task_list_view_init (GtdTaskListView *self)
  *
  * Creates a new #GtdTaskListView
  *
- * Returns: a newly allocated #GtdTaskListView
+ * Returns: (transfer full): a newly allocated #GtdTaskListView
  */
 GtkWidget*
 gtd_task_list_view_new (void)
@@ -874,10 +874,9 @@ gtd_task_list_view_get_list (GtdTaskListView *view)
 /**
  * gtd_task_list_view_set_list:
  * @view: a #GtdTaskListView
+ * @list: (element-type #GtdTask) (nullable): a list of tasks
  *
  * Copies the tasks from @list to @view.
- *
- * Returns:
  */
 void
 gtd_task_list_view_set_list (GtdTaskListView *view,
@@ -930,8 +929,6 @@ gtd_task_list_view_get_readonly (GtdTaskListView *view)
  * @view: a #GtdTaskListView
  *
  * Sets the GtdTaskListView::readonly property of @view.
- *
- * Returns:
  */
 void
 gtd_task_list_view_set_readonly (GtdTaskListView *view,
@@ -990,8 +987,6 @@ gtd_task_list_view_get_task_list (GtdTaskListView *view)
  * @list: a #GtdTaskList
  *
  * Sets the internal #GtdTaskList of @view.
- *
- * Returns:
  */
 void
 gtd_task_list_view_set_task_list (GtdTaskListView *view,
@@ -1087,8 +1082,6 @@ gtd_task_list_view_get_show_list_name (GtdTaskListView *view)
  * @show_list_name: %TRUE to show list names, %FALSE to hide it
  *
  * Whether @view should should it's tasks' list name.
- *
- * Returns:
  */
 void
 gtd_task_list_view_set_show_list_name (GtdTaskListView *view,
@@ -1116,7 +1109,7 @@ gtd_task_list_view_set_show_list_name (GtdTaskListView *view,
 }
 
 /**
- * gtd_task_list_view_get)show_completed:
+ * gtd_task_list_view_get_show_completed:
  * @view: a #GtdTaskListView
  *
  * Returns %TRUE if completed tasks are visible, %FALSE otherwise.
@@ -1137,8 +1130,6 @@ gtd_task_list_view_get_show_completed (GtdTaskListView *view)
  * @show_completed: %TRUE to show completed tasks, %FALSE to hide them
  *
  * Sets the ::show-completed property to @show_completed.
- *
- * Returns:
  */
 void
 gtd_task_list_view_set_show_completed (GtdTaskListView *view,
diff --git a/src/gtd-task-list.c b/src/gtd-task-list.c
index 660ad23..5fee618 100644
--- a/src/gtd-task-list.c
+++ b/src/gtd-task-list.c
@@ -200,6 +200,8 @@ gtd_task_list_class_init (GtdTaskListClass *klass)
 
   /**
    * GtdTaskList::task-added:
+   * @list: a #GtdTaskList
+   * @task: a #GtdTask
    *
    * The ::task-added signal is emmited after a #GtdTask
    * is added to the list.
@@ -217,6 +219,8 @@ gtd_task_list_class_init (GtdTaskListClass *klass)
 
   /**
    * GtdTaskList::task-removed:
+   * @list: a #GtdTaskList
+   * @task: a #GtdTask
    *
    * The ::task-removed signal is emmited after a #GtdTask
    * is removed from the list.
@@ -234,6 +238,8 @@ gtd_task_list_class_init (GtdTaskListClass *klass)
 
   /**
    * GtdTaskList::task-updated:
+   * @list: a #GtdTaskList
+   * @task: a #GtdTask
    *
    * The ::task-updated signal is emmited after a #GtdTask
    * in the list is updated.
@@ -258,8 +264,7 @@ gtd_task_list_init (GtdTaskList *self)
 
 /**
  * gtd_task_list_new:
- * @uid: the unique identifier of the list, usually set
- * by the backend
+ * @provider: (nullable): a #GtdProvider
  *
  * Creates a new list.
  *
@@ -303,10 +308,10 @@ gtd_task_list_get_color (GtdTaskList *list)
 
 /**
  * gtd_task_list_set_color:
+ * @list: a #GtdTaskList
+ * #color: a #GdkRGBA
  *
  * sets the color of @list.
- *
- * Returns:
  */
 void
 gtd_task_list_set_color (GtdTaskList   *list,
@@ -354,10 +359,10 @@ gtd_task_list_get_name (GtdTaskList *list)
 
 /**
  * gtd_task_list_set_name:
+ * @list: a #GtdTaskList
+ * @name: (nullable): the name of @list
  *
  * Sets the @list name to @name.
- *
- * Returns:
  */
 void
 gtd_task_list_set_name (GtdTaskList *list,
@@ -423,8 +428,6 @@ gtd_task_list_get_tasks (GtdTaskList *list)
  * @task: a #GtdTask
  *
  * Adds or updates @task to @list if it's not already present.
- *
- * Returns:
  */
 void
 gtd_task_list_save_task (GtdTaskList *list,
@@ -455,8 +458,6 @@ gtd_task_list_save_task (GtdTaskList *list,
  * @task: a #GtdTask
  *
  * Removes @task from @list if it's inside the list.
- *
- * Returns:
  */
 void
 gtd_task_list_remove_task (GtdTaskList *list,
@@ -520,6 +521,13 @@ gtd_task_list_is_removable (GtdTaskList *list)
   return priv->removable;
 }
 
+/**
+ * gtd_task_list_set_is_removable:
+ * @list: a #GtdTaskList
+ * @is_removable: %TRUE if @list can be deleted, %FALSE otherwise
+ *
+ * Sets whether @list can be deleted or not.
+ */
 void
 gtd_task_list_set_is_removable (GtdTaskList *list,
                                 gboolean     is_removable)
diff --git a/src/gtd-task.c b/src/gtd-task.c
index 557b46a..5e5396a 100644
--- a/src/gtd-task.c
+++ b/src/gtd-task.c
@@ -342,6 +342,14 @@ gtd_task_init (GtdTask *self)
   ;
 }
 
+/**
+ * gtd_task_new:
+ * @component: (nullable): a #ECalComponent
+ *
+ * Creates a new #GtdTask
+ *
+ * Returns: (transfer full): a #GtdTask
+ */
 GtdTask *
 gtd_task_new (ECalComponent *component)
 {
@@ -385,6 +393,14 @@ gtd_task_get_complete (GtdTask *task)
   return completed;
 }
 
+/**
+ * gtd_task_get_component:
+ * @task: a #GtdTask
+ *
+ * Retrieves the internal #ECalComponent of @task.
+ *
+ * Returns: (transfer none): a #ECalComponent
+ */
 ECalComponent*
 gtd_task_get_component (GtdTask *task)
 {
@@ -403,8 +419,6 @@ gtd_task_get_component (GtdTask *task)
  * @complete: the new value
  *
  * Updates the complete state of @task.
- *
- * Returns:
  */
 void
 gtd_task_set_complete (GtdTask  *task,
@@ -529,12 +543,10 @@ gtd_task_get_description (GtdTask *task)
 /**
  * gtd_task_set_description:
  * @task: a #GtdTask
- * @description: the new description, or %NULL
+ * @description: (nullable): the new description, or %NULL
  *
  * Updates the description of @task. The string is not stripped off of
  * spaces to preserve user data.
- *
- * Returns:
  */
 void
 gtd_task_set_description (GtdTask     *task,
@@ -597,11 +609,9 @@ gtd_task_get_due_date (GtdTask *task)
 /**
  * gtd_task_set_due_date:
  * @task: a #GtdTask
- * @dt: a #GDateTime
+ * @dt: (nullable): a #GDateTime
  *
  * Updates the internal @GtdTask::due-date property.
- *
- * Returns:
  */
 void
 gtd_task_set_due_date (GtdTask   *task,
@@ -700,10 +710,10 @@ gtd_task_get_list (GtdTask *task)
 
 /**
  * gtd_task_set_list:
+ * @task: a #GtdTask
+ * @list: (nullable): a #GtdTaskList
  *
  * Sets the parent #GtdTaskList of @task.
- *
- * Returns:
  */
 void
 gtd_task_set_list (GtdTask     *task,
@@ -763,8 +773,6 @@ gtd_task_get_priority (GtdTask *task)
  * Sets the @task priority inside the parent #GtdTaskList. It
  * is up to the interface to handle two or more #GtdTask with
  * the same priority value.
- *
- * Returns:
  */
 void
 gtd_task_set_priority (GtdTask *task,
@@ -812,12 +820,10 @@ gtd_task_get_title (GtdTask *task)
 /**
  * gtd_task_set_title:
  * @task: a #GtdTask
- * @description: the new title, or %NULL
+ * @title: (nullable): the new title, or %NULL
  *
  * Updates the title of @task. The string is stripped off of
  * leading spaces.
- *
- * Returns:
  */
 void
 gtd_task_set_title (GtdTask     *task,
@@ -852,8 +858,6 @@ gtd_task_set_title (GtdTask     *task,
  *
  * Cancels any editing made on @task after the latest
  * call of @gtd_task_save.
- *
- * Returns:
  */
 void
 gtd_task_abort (GtdTask *task)
@@ -872,8 +876,6 @@ gtd_task_abort (GtdTask *task)
  * @task: a #GtdTask
  *
  * Save any changes made on @task.
- *
- * Returns:
  */
 void
 gtd_task_save (GtdTask *task)
@@ -887,6 +889,15 @@ gtd_task_save (GtdTask *task)
   e_cal_component_commit_sequence (priv->component);
 }
 
+/**
+ * gtd_task_compare:
+ * @t1: (nullable): a #GtdTask
+ * @t2: (nullable): a #GtdTask
+ *
+ * Compare @t1 and @t2.
+ *
+ * Returns: %-1 if @t1 comes before @t2, %1 for the opposite, %0 if they're equal
+ */
 gint
 gtd_task_compare (GtdTask *t1,
                   GtdTask *t2)
diff --git a/src/gtd-task.h b/src/gtd-task.h
index c7b17a0..8dde2c8 100644
--- a/src/gtd-task.h
+++ b/src/gtd-task.h
@@ -64,7 +64,7 @@ void                gtd_task_set_list                 (GtdTask              *tas
 gint                gtd_task_get_priority             (GtdTask              *task);
 
 void                gtd_task_set_priority             (GtdTask              *task,
-                                                       gint                  position);
+                                                       gint                  priority);
 
 const gchar*        gtd_task_get_title                (GtdTask              *task);
 
diff --git a/src/gtd-window.c b/src/gtd-window.c
index 08774b8..a24392c 100644
--- a/src/gtd-window.c
+++ b/src/gtd-window.c
@@ -735,8 +735,6 @@ gtd_window_get_manager (GtdWindow *window)
  * @notification: a #GtdNotification
  *
  * Shows a notification on the top of the main window.
- *
- * Returns:
  */
 void
 gtd_window_notify (GtdWindow       *window,
@@ -757,8 +755,6 @@ gtd_window_notify (GtdWindow       *window,
  * @notification: a #GtdNotification
  *
  * Cancels @notification.
- *
- * Returns:
  */
 void
 gtd_window_cancel_notification (GtdWindow       *window,
@@ -795,8 +791,6 @@ gtd_window_get_mode (GtdWindow *window)
  * @mode: a #GtdWindowMode
  *
  * Sets the current window mode to @mode.
- *
- * Returns:
  */
 void
 gtd_window_set_mode (GtdWindow     *window,
diff --git a/src/interfaces/gtd-activatable.c b/src/interfaces/gtd-activatable.c
index 5db8c19..f14c567 100644
--- a/src/interfaces/gtd-activatable.c
+++ b/src/interfaces/gtd-activatable.c
@@ -85,6 +85,8 @@ gtd_activatable_default_init (GtdActivatableInterface *iface)
 
   /**
    * GtdActivatable::panel-added:
+   * @activatable: a #GtdActivatable
+   * @panel: a #GtdPanel
    *
    * The ::panel-added signal is emmited after a #GtdPanel
    * is connected.
@@ -102,6 +104,8 @@ gtd_activatable_default_init (GtdActivatableInterface *iface)
 
   /**
    * GtdActivatable::panel-removed:
+   * @activatable: a #GtdActivatable
+   * @panel: a #GtdPanel
    *
    * The ::panel-removed signal is emmited after a #GtdPanel
    * is removed from the list.
@@ -119,6 +123,8 @@ gtd_activatable_default_init (GtdActivatableInterface *iface)
 
   /**
    * GtdActivatable::provider-added:
+   * @activatable: a #GtdActivatable
+   * @provider: a #GtdProvider
    *
    * The ::provider-added signal is emmited after a #GtdProvider
    * is connected.
@@ -136,6 +142,8 @@ gtd_activatable_default_init (GtdActivatableInterface *iface)
 
   /**
    * GtdActivatable::provider-changed:
+   * @activatable: a #GtdActivatable
+   * @provider: a #GtdProvider
    *
    * The ::provider-changed signal is emmited after a #GtdProvider
    * has any of it's properties changed.
@@ -153,6 +161,8 @@ gtd_activatable_default_init (GtdActivatableInterface *iface)
 
   /**
    * GtdActivatable::provider-removed:
+   * @activatable: a #GtdActivatable
+   * @provider: a #GtdProvider
    *
    * The ::provider-removed signal is emmited after a #GtdProvider
    * is disconnected.
@@ -169,6 +179,14 @@ gtd_activatable_default_init (GtdActivatableInterface *iface)
                                             GTD_TYPE_PROVIDER);
 }
 
+/**
+ * gtd_activatable_get_preferences_panel:
+ * @activatable: a #GtdActivatable
+ *
+ * Retrieve the preferences panel of @activatable if any.
+ *
+ * Returns: (transfer none): a #GtkWidget, or %NULL
+ */
 GtkWidget*
 gtd_activatable_get_preferences_panel (GtdActivatable *activatable)
 {
@@ -178,6 +196,14 @@ gtd_activatable_get_preferences_panel (GtdActivatable *activatable)
   return GTD_ACTIVATABLE_GET_IFACE (activatable)->get_preferences_panel (activatable);
 }
 
+/**
+ * gtd_activatable_get_panels:
+ * @activatable: a #GtdActivatable
+ *
+ * Retrieve the panel list of @activatable if any.
+ *
+ * Returns: (transfer none) (element-type #GtdPanel): a #GList
+ */
 GList*
 gtd_activatable_get_panels (GtdActivatable *activatable)
 {
@@ -187,6 +213,14 @@ gtd_activatable_get_panels (GtdActivatable *activatable)
   return GTD_ACTIVATABLE_GET_IFACE (activatable)->get_panels (activatable);
 }
 
+/**
+ * gtd_activatable_get_providers:
+ * @activatable: a #GtdActivatable
+ *
+ * Retrieve the providers of @activatable if any.
+ *
+ * Returns: (transfer none) (element-type #GtdProvider): a #GList
+ */
 GList*
 gtd_activatable_get_providers (GtdActivatable *activatable)
 {
diff --git a/src/interfaces/gtd-panel.c b/src/interfaces/gtd-panel.c
index c93697d..770a707 100644
--- a/src/interfaces/gtd-panel.c
+++ b/src/interfaces/gtd-panel.c
@@ -75,6 +75,14 @@ gtd_panel_default_init (GtdPanelInterface *iface)
 
 }
 
+/**
+ * gtd_panel_get_name:
+ * @panel: a #GtdPanel
+ *
+ * Retrieves the name of @panel
+ *
+ * Returns: (transfer none): the name of @panel
+ */
 const gchar*
 gtd_panel_get_name (GtdPanel *panel)
 {
@@ -84,6 +92,14 @@ gtd_panel_get_name (GtdPanel *panel)
   return GTD_PANEL_GET_IFACE (panel)->get_name (panel);
 }
 
+/**
+ * gtd_panel_get_title:
+ * @panel: a #GtdPanel
+ *
+ * Retrieves the title of @panel
+ *
+ * Returns: (transfer none): the title of @panel
+ */
 const gchar*
 gtd_panel_get_title (GtdPanel *panel)
 {
@@ -93,6 +109,20 @@ gtd_panel_get_title (GtdPanel *panel)
   return GTD_PANEL_GET_IFACE (panel)->get_title (panel);
 }
 
+/**
+ * gtd_panel_get_header_widgets:
+ * @panel: a #GtdPanel
+ *
+ * Retrieves the list of widgets to be placed at headerbar. The
+ * position of the widget is determined by the #GtkWidget::halign
+ * property.
+ *
+ * Widgets with @GTK_ALIGN_START halign will be packed into the
+ * start of the headerbar, and @GTK_ALIGN_END at the end. Other
+ * values are silently ignored.
+ *
+ * Returns: (transfer container) (element-type #GtkWidget): the list of #GtkWidget
+ */
 GList*
 gtd_panel_get_header_widgets (GtdPanel *panel)
 {
@@ -102,6 +132,14 @@ gtd_panel_get_header_widgets (GtdPanel *panel)
   return GTD_PANEL_GET_IFACE (panel)->get_header_widgets (panel);
 }
 
+/**
+ * gtd_panel_get_menu:
+ * @panel: a #GtdPanel
+ *
+ * Retrieves the gear menu of @panel.
+ *
+ * Returns: (transfer none): a #GMenu
+ */
 const GMenu*
 gtd_panel_get_menu (GtdPanel *panel)
 {
diff --git a/src/interfaces/gtd-provider.c b/src/interfaces/gtd-provider.c
index 6c39b0c..80c27fb 100644
--- a/src/interfaces/gtd-provider.c
+++ b/src/interfaces/gtd-provider.c
@@ -98,6 +98,8 @@ gtd_provider_default_init (GtdProviderInterface *iface)
 
   /**
    * GtdProvider::list-added:
+   * @provider: a #GtdProvider
+   * @list: a #GtdTaskList
    *
    * The ::list-added signal is emmited after a #GtdTaskList
    * is connected.
@@ -113,8 +115,10 @@ gtd_provider_default_init (GtdProviderInterface *iface)
                                       1,
                                       GTD_TYPE_TASK_LIST);
 
-/**
+  /**
    * GtdProvider::list-changed:
+   * @provider: a #GtdProvider
+   * @list: a #GtdTaskList
    *
    * The ::list-changed signal is emmited after a #GtdTaskList
    * has any of it's properties changed.
@@ -131,7 +135,9 @@ gtd_provider_default_init (GtdProviderInterface *iface)
                                         GTD_TYPE_TASK_LIST);
 
   /**
-   * GtdManager::list-removed:
+   * GtdProvider::list-removed:
+   * @provider: a #GtdProvider
+   * @list: a #GtdTaskList
    *
    * The ::list-removed signal is emmited after a #GtdTaskList
    * is disconnected.
@@ -148,6 +154,14 @@ gtd_provider_default_init (GtdProviderInterface *iface)
                                         GTD_TYPE_TASK_LIST);
 }
 
+/**
+ * gtd_provider_get_id:
+ * @provider: a #GtdProvider
+ *
+ * Retrieves the identifier of @provider.
+ *
+ * Returns: (transfer none): the id of @provider
+ */
 const gchar*
 gtd_provider_get_id (GtdProvider *provider)
 {
@@ -157,6 +171,14 @@ gtd_provider_get_id (GtdProvider *provider)
   return GTD_PROVIDER_GET_IFACE (provider)->get_id (provider);
 }
 
+/**
+ * gtd_provider_get_name:
+ * @provider: a #GtdProvider
+ *
+ * Retrieves the user-visible name of @provider.
+ *
+ * Returns: (transfer none): the name of @provider
+ */
 const gchar*
 gtd_provider_get_name (GtdProvider *provider)
 {
@@ -166,6 +188,14 @@ gtd_provider_get_name (GtdProvider *provider)
   return GTD_PROVIDER_GET_IFACE (provider)->get_name (provider);
 }
 
+/**
+ * gtd_provider_get_description:
+ * @provider: a #GtdProvider
+ *
+ * Retrieves the description of @provider.
+ *
+ * Returns: (transfer none): the description of @provider
+ */
 const gchar*
 gtd_provider_get_description (GtdProvider *provider)
 {
@@ -175,6 +205,16 @@ gtd_provider_get_description (GtdProvider *provider)
   return GTD_PROVIDER_GET_IFACE (provider)->get_description (provider);
 }
 
+/**
+ * gtd_provider_get_enabled:
+ * @provider: a #GtdProvider
+ *
+ * Retrieves whether @provider is enabled or not. A disabled
+ * provider cannot be selected to be default nor be selected
+ * to add tasks to it.
+ *
+ * Returns: %TRUE if provider is enabled, %FALSE otherwise.
+ */
 gboolean
 gtd_provider_get_enabled (GtdProvider *provider)
 {
@@ -184,6 +224,14 @@ gtd_provider_get_enabled (GtdProvider *provider)
   return GTD_PROVIDER_GET_IFACE (provider)->get_enabled (provider);
 }
 
+/**
+ * gtd_provider_get_icon:
+ * @provider: a #GtdProvider
+ *
+ * The icon of @provider.
+ *
+ * Returns: (transfer none): a #GIcon
+ */
 GIcon*
 gtd_provider_get_icon (GtdProvider *provider)
 {
@@ -202,6 +250,13 @@ gtd_provider_get_edit_panel (GtdProvider *provider)
   return GTD_PROVIDER_GET_IFACE (provider)->get_edit_panel (provider);
 }
 
+/**
+ * gtd_provider_create_task:
+ * @provider: a #GtdProvider
+ * @task: a #GtdTask
+ *
+ * Creates the given task in @provider.
+ */
 void
 gtd_provider_create_task (GtdProvider *provider,
                           GtdTask     *task)
@@ -212,6 +267,13 @@ gtd_provider_create_task (GtdProvider *provider,
   GTD_PROVIDER_GET_IFACE (provider)->create_task (provider, task);
 }
 
+/**
+ * gtd_provider_update_task:
+ * @provider: a #GtdProvider
+ * @task: a #GtdTask
+ *
+ * Updates the given task in @provider.
+ */
 void
 gtd_provider_update_task (GtdProvider *provider,
                           GtdTask     *task)
@@ -222,6 +284,13 @@ gtd_provider_update_task (GtdProvider *provider,
   GTD_PROVIDER_GET_IFACE (provider)->update_task (provider, task);
 }
 
+/**
+ * gtd_provider_remove_task:
+ * @provider: a #GtdProvider
+ * @task: a #GtdTask
+ *
+ * Removes the given task from @provider.
+ */
 void
 gtd_provider_remove_task (GtdProvider *provider,
                           GtdTask     *task)
@@ -232,6 +301,13 @@ gtd_provider_remove_task (GtdProvider *provider,
   GTD_PROVIDER_GET_IFACE (provider)->remove_task (provider, task);
 }
 
+/**
+ * gtd_provider_create_task_list:
+ * @provider: a #GtdProvider
+ * @list: a #GtdTaskList
+ *
+ * Creates the given list in @provider.
+ */
 void
 gtd_provider_create_task_list (GtdProvider *provider,
                                GtdTaskList *list)
@@ -242,6 +318,13 @@ gtd_provider_create_task_list (GtdProvider *provider,
   GTD_PROVIDER_GET_IFACE (provider)->create_task_list (provider, list);
 }
 
+/**
+ * gtd_provider_update_task_list:
+ * @provider: a #GtdProvider
+ * @list: a #GtdTaskList
+ *
+ * Updates the given list in @provider.
+ */
 void
 gtd_provider_update_task_list (GtdProvider *provider,
                                GtdTaskList *list)
@@ -251,7 +334,13 @@ gtd_provider_update_task_list (GtdProvider *provider,
 
   GTD_PROVIDER_GET_IFACE (provider)->update_task_list (provider, list);
 }
-
+/**
+ * gtd_provider_remove_task_list:
+ * @provider: a #GtdProvider
+ * @list: a #GtdTaskList
+ *
+ * Removes the given list from @provider.
+ */
 void
 gtd_provider_remove_task_list (GtdProvider *provider,
                                GtdTaskList *list)
@@ -261,7 +350,14 @@ gtd_provider_remove_task_list (GtdProvider *provider,
 
   GTD_PROVIDER_GET_IFACE (provider)->remove_task_list (provider, list);
 }
-
+/**
+ * gtd_provider_get_task_lists:
+ * @provider: a #GtdProvider
+ *
+ * Retrieves the tasklists that this provider contains.
+ *
+ * Returns: (transfer container) (element-type #GtdTaskList): the list of tasks, or %NULL
+ */
 GList*
 gtd_provider_get_task_lists (GtdProvider *provider)
 {
diff --git a/src/notification/gtd-notification.c b/src/notification/gtd-notification.c
index f5f89f4..8bd0756 100644
--- a/src/notification/gtd-notification.c
+++ b/src/notification/gtd-notification.c
@@ -270,6 +270,8 @@ gtd_notification_init (GtdNotification *self)
 
 /**
  * gtd_notification_new:
+ * @text: (nullable): text of the notification
+ * @timeout: time for the notification to stay visible
  *
  * Creates a new notification with @text and @timeout. If @timeout is
  * 0, the notification is indefinitely displayed.
@@ -288,11 +290,12 @@ gtd_notification_new (const gchar *text,
 
 /**
  * gtd_notification_set_primary_action:
+ * @notification: a #GtdNotification
+ * @func: (closure user_data) (scope call) (nullable): the primary action function
+ * @user_data: data passed to @func
  *
  * Sets the primary action of @notification, which is triggered
  * on dismiss or timeout.
- *
- * Returns:
  */
 void
 gtd_notification_set_primary_action (GtdNotification           *notification,
@@ -320,11 +323,13 @@ gtd_notification_set_primary_action (GtdNotification           *notification,
 
 /**
  * gtd_notification_set_secondary_action:
+ * @notification: a #GtdNotification
+ * @name: the name of the secondary action
+ * @func: (closure user_data) (scope call) (nullable): the secondary action function
+ * @user_data: data passed to @func
  *
  * Sets the secondary action of @notification, which is triggered
  * only on user explicit input.
- *
- * Returns:
  */
 void
 gtd_notification_set_secondary_action (GtdNotification           *notification,
@@ -361,6 +366,7 @@ gtd_notification_set_secondary_action (GtdNotification           *notification,
 
 /**
  * gtd_notification_get_text:
+ * @notification: a #GtdNotification
  *
  * Gets the text of @notification.
  *
@@ -376,10 +382,10 @@ gtd_notification_get_text (GtdNotification *notification)
 
 /**
  * gtd_notification_set_text:
+ * @notification: a #GtdNotification
+ * @text: the user-visible text of @notification
  *
  * Sets the text of @notification to @text.
- *
- * Returns:
  */
 void
 gtd_notification_set_text (GtdNotification *notification,
@@ -417,10 +423,10 @@ gtd_notification_get_timeout (GtdNotification *notification)
 
 /**
  * gtd_notification_set_timeout:
+ * @notification: a #GtdNotification
+ * @timeout: the time to wait before running @notification, in miliseconds
  *
  * Sets the timeout of @notification to @timeout.
- *
- * Returns:
  */
 void
 gtd_notification_set_timeout (GtdNotification *notification,
@@ -442,10 +448,9 @@ gtd_notification_set_timeout (GtdNotification *notification,
 
 /**
  * gtd_notification_execute_primary_action:
+ * @notification: a #GtdNotification
  *
  * Executes the primary action of @notification if set.
- *
- * Returns:
  */
 void
 gtd_notification_execute_primary_action (GtdNotification *notification)
@@ -464,10 +469,9 @@ gtd_notification_execute_primary_action (GtdNotification *notification)
 
 /**
  * gtd_notification_execute_secondary_action:
+ * @notification: a #GtdNotification
  *
  * Executes the secondary action of @notification if any.
- *
- * Returns:
  */
 void
 gtd_notification_execute_secondary_action (GtdNotification *notification)
@@ -490,11 +494,10 @@ gtd_notification_execute_secondary_action (GtdNotification *notification)
 
 /**
  * gtd_notification_start:
+ * @notification: a #GtdNotification
  *
  * Starts the timeout of notification. Use @gtd_notification_stop
  * to stop it.
- *
- * Returns:
  */
 void
 gtd_notification_start (GtdNotification *notification)
@@ -521,11 +524,10 @@ gtd_notification_start (GtdNotification *notification)
 
 /**
  * gtd_notification_stop:
+ * @notification: a #GtdNotification
  *
  * Stops the timeout of notification. Use @gtd_notification_start
  * to start it.
- *
- * Returns:
  */
 void
 gtd_notification_stop (GtdNotification *notification)
diff --git a/src/notification/gtd-notification.h b/src/notification/gtd-notification.h
index 2ae2298..b0c97ff 100644
--- a/src/notification/gtd-notification.h
+++ b/src/notification/gtd-notification.h
@@ -31,6 +31,14 @@ G_BEGIN_DECLS
 
 G_DECLARE_FINAL_TYPE (GtdNotification, gtd_notification, GTD, NOTIFICATION, GtdObject)
 
+/**
+ * GtdNotificationActionFunc:
+ * @notification: the #GtdNotification running the function
+ * @user_data: (closure): user data
+ *
+ * Will be called when the primary or secondary action of @notification
+ * is executed.
+ */
 typedef void (*GtdNotificationActionFunc) (GtdNotification *notification,
                                            gpointer         user_data);
 
diff --git a/src/plugin/gtd-plugin-dialog.c b/src/plugin/gtd-plugin-dialog.c
index 36eba3f..c0adfe0 100644
--- a/src/plugin/gtd-plugin-dialog.c
+++ b/src/plugin/gtd-plugin-dialog.c
@@ -18,6 +18,7 @@
 
 #include "interfaces/gtd-activatable.h"
 #include "gtd-manager.h"
+#include "gtd-manager-protected.h"
 #include "gtd-plugin-manager.h"
 #include "gtd-plugin-dialog.h"
 


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