GNOME.org
 

[gnome-todo] project: improve widgets' documentation

commit 07f2fbeba3b87178acddbbffdcbc12e4eb77da0a
Author: Georges Basile Stavracas Neto <georges stavracas gmail com>
Date:   Sat Oct 8 11:38:06 2016 -0300

    project: improve widgets' documentation

 doc/reference/Makefile.am                  |    3 +-
 doc/reference/images/notification.png      |  Bin 0 -> 5132 bytes
 src/engine/gtd-manager.c                   |   17 ++++++++++-
 src/gtd-object.c                           |   11 +++++++
 src/gtd-task-list-view.c                   |   30 ++++++++++++++++++-
 src/gtd-task-list.c                        |   11 +++++++
 src/gtd-task-row.c                         |    2 -
 src/gtd-task.c                             |   11 +++++++
 src/gtd-window.c                           |   13 ++++++++
 src/interfaces/gtd-activatable.c           |   27 +++++++++++++++++
 src/interfaces/gtd-panel.c                 |   21 +++++++++++++
 src/interfaces/gtd-provider.c              |   14 +++++++++
 src/notification/gtd-notification-widget.c |    2 -
 src/notification/gtd-notification.c        |   44 ++++++++++++++++++++++++++--
 src/provider/gtd-provider-row.c            |    2 -
 src/provider/gtd-provider-selector.c       |    6 ----
 16 files changed, 196 insertions(+), 18 deletions(-)
---
diff --git a/doc/reference/Makefile.am b/doc/reference/Makefile.am
index 8c25c5f..09dfedc 100644
--- a/doc/reference/Makefile.am
+++ b/doc/reference/Makefile.am
@@ -80,7 +80,8 @@ IGNORE_HFILES = \
        gtd-types.h
 
 # Images to copy into HTML directory.
-HTML_IMAGES =
+HTML_IMAGES = \
+       images/notification.png
 
 # Extra SGML files that are included by $(DOC_MAIN_SGML_FILE).
 # e.g. content_files=running.sgml building.sgml changes-2.0.sgml
diff --git a/doc/reference/images/notification.png b/doc/reference/images/notification.png
new file mode 100644
index 0000000..331e651
Binary files /dev/null and b/doc/reference/images/notification.png differ
diff --git a/src/engine/gtd-manager.c b/src/engine/gtd-manager.c
index e653cf4..125fcfa 100644
--- a/src/engine/gtd-manager.c
+++ b/src/engine/gtd-manager.c
@@ -26,6 +26,21 @@
 
 #include <glib/gi18n.h>
 
+/**
+ * SECTION:gtd-manager
+ * @short_description:bridge between plugins and GNOME To Do
+ * @title:GtdManager
+ * @stability:Unstable
+ * @see_also:#GtdNotification,#GtdActivatable
+ *
+ * The #GtdManager object is a singleton object that exposes all the data
+ * inside the plugin to GNOME To Do, and vice-versa. From here, plugins have
+ * access to all the tasklists, tasks and panels of the other plugins.
+ *
+ * Objects can use gtd_manager_emit_error_message() to send errors to GNOME
+ * To Do. This will create a #GtdNotification internally.
+ */
+
 typedef struct
 {
   GSettings             *settings;
@@ -194,7 +209,7 @@ gtd_manager_class_init (GtdManagerClass *klass)
                              "The plugin manager",
                              "The plugin manager of the application",
                              GTD_TYPE_PLUGIN_MANAGER,
-                             G_PARAM_READABLE));
+                             G_PARAM_READABLE | G_PARAM_PRIVATE));
 
   /**
    * GtdManager::list-added:
diff --git a/src/gtd-object.c b/src/gtd-object.c
index 33603d5..12d5101 100644
--- a/src/gtd-object.c
+++ b/src/gtd-object.c
@@ -20,6 +20,17 @@
 
 #include <glib/gi18n.h>
 
+/**
+ * SECTION:gtd-object
+ * @Short_description: base class for loadable and uniquely identifiable objects
+ * @Title: GtdObject
+ *
+ * #GtdObject is the base class of many object in GNOME To Do, and it useful for
+ * when a given object is loadable and/or uniquely identifiable. Some examples of
+ * it are #GtdTask, #GtdTaskList and #GtdNotification.
+ *
+ */
+
 typedef struct
 {
   gboolean       ready;
diff --git a/src/gtd-task-list-view.c b/src/gtd-task-list-view.c
index 72cb8f5..4dc7e6e 100644
--- a/src/gtd-task-list-view.c
+++ b/src/gtd-task-list-view.c
@@ -31,6 +31,34 @@
 #include <glib/gi18n.h>
 #include <gtk/gtk.h>
 
+/**
+ * SECTION:gtd-task-list-view
+ * @Short_description: A widget to display tasklists
+ * @Title:GtdTaskListView
+ *
+ * The #GtdTaskListView widget shows the tasks of a #GtdTaskList with
+ * various options to fine-tune the appearance. Alternatively, one can
+ * pass a #GList of #GtdTask objects.
+ *
+ * It supports custom sorting and header functions, so the tasks can be
+ * sorted in various ways. See the "Today" and "Scheduled" panels for reference
+ * implementations.
+ *
+ * Example:
+ * |[
+ * GtdTaskListView *view = gtd_task_list_view_new ();
+ *
+ * gtd_task_list_view_set_list (view, list);
+ *
+ * // Hide the '+ New task' row
+ * gtd_task_list_view_set_show_new_task_row (view, FALSE);
+ *
+ * // Date which tasks will be automatically assigned
+ * gtd_task_list_view_set_default_date (view, now);
+ * ]|
+ *
+ */
+
 typedef struct
 {
   GtdArrowFrame         *arrow_frame;
@@ -1049,7 +1077,7 @@ gtd_task_list_view_get_show_new_task_row (GtdTaskListView *self)
  * gtd_task_list_view_set_show_new_task_row:
  * @view: a #GtdTaskListView
  *
- * Sets the GtdTaskListView::show-new-task-mode property of @view.
+ * Sets the #GtdTaskListView:show-new-task-mode property of @view.
  */
 void
 gtd_task_list_view_set_show_new_task_row (GtdTaskListView *view,
diff --git a/src/gtd-task-list.c b/src/gtd-task-list.c
index 656f2ec..d90bf4a 100644
--- a/src/gtd-task-list.c
+++ b/src/gtd-task-list.c
@@ -23,6 +23,17 @@
 #include <glib/gi18n.h>
 #include <libecal/libecal.h>
 
+/**
+ * SECTION:gtd-task-list
+ * @short_description:a list of tasks
+ * @title:GtdTaskList
+ * @stability:Unstable
+ * @see_also:#GtdTask
+ *
+ * A #GtdTaskList represents a task list, and contains a list of tasks, a color,
+ * a name and the provider who generated it.
+ */
+
 typedef struct
 {
   GList               *tasks;
diff --git a/src/gtd-task-row.c b/src/gtd-task-row.c
index bbfa799..c362fa6 100644
--- a/src/gtd-task-row.c
+++ b/src/gtd-task-row.c
@@ -558,8 +558,6 @@ gtd_task_row_get_task (GtdTaskRow *row)
  *
  * Sets the internal #GtdTask of @row. The task must be set to %NULL
  * before setting GtdObject::new-task-mode to %TRUE.
- *
- * Returns:
  */
 void
 gtd_task_row_set_task (GtdTaskRow *row,
diff --git a/src/gtd-task.c b/src/gtd-task.c
index 4cb28f3..d1dac7a 100644
--- a/src/gtd-task.c
+++ b/src/gtd-task.c
@@ -24,6 +24,17 @@
 #include <libical/icaltime.h>
 #include <libical/icaltimezone.h>
 
+/**
+ * SECTION:gtd-task
+ * @short_description: a task
+ * @title:GtdTask
+ * @stability:Unstable
+ * @see_also:#GtdTaskList
+ *
+ * A #GtdTask is an object that represents a task. All #GtdTasks
+ * must be inside a #GtdTaskList.
+ */
+
 typedef struct
 {
   gchar           *description;
diff --git a/src/gtd-window.c b/src/gtd-window.c
index 8f8daa2..baf7fbd 100644
--- a/src/gtd-window.c
+++ b/src/gtd-window.c
@@ -34,6 +34,19 @@
 
 #include <glib/gi18n.h>
 
+/**
+ * SECTION:gtd-window
+ * @short_description:main window
+ * @title:GtdWindow
+ * @stability:Unstable
+ * @see_also:#GtdNotification
+ *
+ * The #GtdWindow is the main application window of GNOME To Do. Objects should
+ * use this class to send notifications (see gtd_window_notify()), cancel notifications
+ * (see gtd_window_cancel_notification()), change between selection and normal mode
+ * and fine-tune the headerbar.
+ */
+
 typedef struct
 {
   GtkWidget                     *cancel_selection_button;
diff --git a/src/interfaces/gtd-activatable.c b/src/interfaces/gtd-activatable.c
index 73dedbc..e9eddf4 100644
--- a/src/interfaces/gtd-activatable.c
+++ b/src/interfaces/gtd-activatable.c
@@ -20,6 +20,33 @@
 #include "gtd-panel.h"
 #include "gtd-provider.h"
 
+/**
+ * SECTION:gtd-activatable
+ * @short_description:entry point for plugins
+ * @title:GtdActivatable
+ * @stability:Unstable
+ *
+ * The #GtdActivatable interface is the interface plugins must
+ * implement in order to be seen by GNOME To Do.
+ *
+ * When plugins are loaded, the gtd_activatable_activate() vfunc
+ * is called. Use this vfunc to load anything that depends on GNOME
+ * To Do.
+ *
+ * When plugins are unloaded, the gtd_activatable_deactivate() vfunc
+ * if called. Ideally, the implementation should undo everything that
+ * was done on gtd_activatable_activate().
+ *
+ * A plugin implementation may expose one or more #GtdProvider instances,
+ * which are the data sources of GNOME To Do. See the 'eds' plugin for
+ * a reference on how to expose one ('local') and multiple (Online Accounts)
+ * providers.
+ *
+ * Plugins may also expose one or more #GtdPanel implementations.
+ *
+ * Optionally, a plugin may expose a preferences panel. See gtd_activatable_get_preferences_panel().
+ */
+
 G_DEFINE_INTERFACE (GtdActivatable, gtd_activatable, G_TYPE_OBJECT)
 
 enum
diff --git a/src/interfaces/gtd-panel.c b/src/interfaces/gtd-panel.c
index 124a1b1..fbf00c5 100644
--- a/src/interfaces/gtd-panel.c
+++ b/src/interfaces/gtd-panel.c
@@ -18,6 +18,27 @@
 
 #include "gtd-panel.h"
 
+/**
+ * SECTION:gtd-panel
+ * @short_description: interface for panels
+ * @title:GtdPanel
+ * @stability:Unstable
+ *
+ * The #GtdPanel interface must be implemented by plugins that want
+ * a given widget to be shown as a panel in the main window. Examples
+ * of panels are the "Today" and "Scheduled" panels.
+ *
+ * A panel must have a unique name (see #GtdPanel:name) and a title.
+ * The title can change dynamically. Avoid long titles.
+ *
+ * The panel may also provide header widgets, which will be placed
+ * in the headerbar according to the #GtkWidget:halign property. See
+ * gtd_panel_get_header_widgets() for a detailed explanation.
+ *
+ * At last, a #GtdPanel implementation may provide a #GMenu that will
+ * be appended to the window menu.
+ */
+
 G_DEFINE_INTERFACE (GtdPanel, gtd_panel, GTK_TYPE_WIDGET)
 
 static void
diff --git a/src/interfaces/gtd-provider.c b/src/interfaces/gtd-provider.c
index 0c5e823..6ff3626 100644
--- a/src/interfaces/gtd-provider.c
+++ b/src/interfaces/gtd-provider.c
@@ -19,6 +19,20 @@
 #include "gtd-provider.h"
 #include "gtd-task-list.h"
 
+/**
+ * SECTION:gtd-provider
+ * @short_description:data sources for GNOME To do
+ * @title: GtdProvider
+ * @stability:Unstable
+ *
+ * The #GtdProvider is the interface that GNOME To Do uses to
+ * connect to data sources. It must provide ways to create, update
+ * and remove tasks and tasklists.
+ *
+ * A provider implementation must also expose which is the default
+ * tasklist among the tasklists it manages.
+ */
+
 G_DEFINE_INTERFACE (GtdProvider, gtd_provider, GTD_TYPE_OBJECT)
 
 enum
diff --git a/src/notification/gtd-notification-widget.c b/src/notification/gtd-notification-widget.c
index 701802e..2ef79d8 100644
--- a/src/notification/gtd-notification-widget.c
+++ b/src/notification/gtd-notification-widget.c
@@ -272,8 +272,6 @@ gtd_notification_widget_notify (GtdNotificationWidget *widget,
  *
  * Cancel @notification from being displayed. If @notification is not
  * queued, nothing happens.
- *
- * Returns:
  */
 void
 gtd_notification_widget_cancel (GtdNotificationWidget *widget,
diff --git a/src/notification/gtd-notification.c b/src/notification/gtd-notification.c
index 8bd0756..5d8861b 100644
--- a/src/notification/gtd-notification.c
+++ b/src/notification/gtd-notification.c
@@ -21,6 +21,43 @@
 
 #include <glib/gi18n.h>
 
+/**
+ * SECTION:gtd-notification
+ * @short_description:a notification with actions
+ * @title:GtdNotification
+ * @image:notification.png
+ * @stability:Stable
+ *
+ * The #GtdNotification represents a notification shown at the top of
+ * the window. The action can have a primary action that is called when
+ * the notification is gone.
+ *
+ * Optionally, the notification may have a secondary action (see gtd_notification_set_secondary_action())
+ * shown as a button.
+ *
+ * The notification may also have a timeout, which is how long the notification
+ * is displayed. By default, the timeout is 7.5 seconds.
+ *
+ * Example:
+ * |[
+ * GtdNotification *notification;
+ *
+ * notification = gtd_notification_new ("Something happened!", 7500);
+ *
+ * gtd_notification_set_primary_action (notification,
+ *                                      called_when_notification_is_closed,
+ *                                      self);
+ *
+ * gtd_notification_set_secondary_action (notification,
+ *                                        "Details",
+ *                                        show_details,
+ *                                        self);
+ * [...]
+ *
+ * gtd_window_send_notification (window, notification);
+ * ]|
+ */
+
 typedef struct
 {
   gchar              *text;
@@ -426,7 +463,8 @@ gtd_notification_get_timeout (GtdNotification *notification)
  * @notification: a #GtdNotification
  * @timeout: the time to wait before running @notification, in miliseconds
  *
- * Sets the timeout of @notification to @timeout.
+ * Sets the timeout of @notification to @timeout. Set it to %0 to disable
+ * the timeout.
  */
 void
 gtd_notification_set_timeout (GtdNotification *notification,
@@ -496,7 +534,7 @@ gtd_notification_execute_secondary_action (GtdNotification *notification)
  * gtd_notification_start:
  * @notification: a #GtdNotification
  *
- * Starts the timeout of notification. Use @gtd_notification_stop
+ * Starts the timeout of notification. Use gtd_notification_stop()
  * to stop it.
  */
 void
@@ -526,7 +564,7 @@ gtd_notification_start (GtdNotification *notification)
  * gtd_notification_stop:
  * @notification: a #GtdNotification
  *
- * Stops the timeout of notification. Use @gtd_notification_start
+ * Stops the timeout of notification. Use gtd_notification_start()
  * to start it.
  */
 void
diff --git a/src/provider/gtd-provider-row.c b/src/provider/gtd-provider-row.c
index 6bebddd..bec632a 100644
--- a/src/provider/gtd-provider-row.c
+++ b/src/provider/gtd-provider-row.c
@@ -224,8 +224,6 @@ gtd_provider_row_get_selected (GtdProviderRow *row)
  * mark is visible)
  *
  * Sets @row as the currently selected row.
- *
- * Returns:
  */
 void
 gtd_provider_row_set_selected (GtdProviderRow *row,
diff --git a/src/provider/gtd-provider-selector.c b/src/provider/gtd-provider-selector.c
index 3398062..dd662eb 100644
--- a/src/provider/gtd-provider-selector.c
+++ b/src/provider/gtd-provider-selector.c
@@ -547,8 +547,6 @@ gtd_provider_selector_new (void)
  * gtd_provider_selector_show_local:
  *
  * Shows a row for local provider item.
- *
- * Returns:
  */
 void
 gtd_provider_selector_show_local (GtdProviderSelector *selector,
@@ -592,8 +590,6 @@ gtd_provider_selector_get_select_default (GtdProviderSelector *selector)
  * @select_default: %TRUE to auto select the default provider location.
  *
  * Whether @selector should select the default provider location by default.
- *
- * Returns:
  */
 void
 gtd_provider_selector_set_select_default (GtdProviderSelector *selector,
@@ -675,8 +671,6 @@ gtd_provider_selector_get_selected_provider (GtdProviderSelector *selector)
  * @provider: a #GtdProvider
  *
  * Selects @provider in the given #GtdProviderSelector.
- *
- * Returns:
  */
 void
 gtd_provider_selector_set_selected_provider (GtdProviderSelector *selector,
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]