[evolution-data-server] Calendar: Fixing gtk-doc comments and adding gtk-doc section headers
- From: Tristan Van Berkom <tvb src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [evolution-data-server] Calendar: Fixing gtk-doc comments and adding gtk-doc section headers
- Date: Fri, 6 Dec 2013 10:37:09 +0000 (UTC)
commit 010ab87a67b2552ca0d540da6d7c52d2092c64f4
Author: Tristan Van Berkom <tristan upstairslabs com>
Date: Fri Dec 6 14:59:14 2013 +0900
Calendar: Fixing gtk-doc comments and adding gtk-doc section headers
calendar/libecal/e-cal-client-view.c | 27 ++++++-
calendar/libecal/e-cal-client.c | 9 ++
calendar/libecal/e-cal-client.h | 4 +-
calendar/libecal/e-cal-component.c | 12 +++-
calendar/libecal/e-cal-system-timezone.c | 7 +-
calendar/libecal/e-cal-types.h | 64 ++++++++++++--
calendar/libecal/e-cal-util.c | 24 +++--
calendar/libecal/e-cal.h | 62 ++++++++++++--
calendar/libedata-cal/e-cal-backend-cache.c | 15 +++-
calendar/libedata-cal/e-cal-backend-cache.h | 13 +++
calendar/libedata-cal/e-cal-backend-factory.c | 9 ++
calendar/libedata-cal/e-cal-backend-factory.h | 21 +++++
calendar/libedata-cal/e-cal-backend-intervaltree.c | 16 +++-
calendar/libedata-cal/e-cal-backend-intervaltree.h | 12 +++
calendar/libedata-cal/e-cal-backend-sexp.c | 9 ++
calendar/libedata-cal/e-cal-backend-sexp.h | 13 +++
calendar/libedata-cal/e-cal-backend-store.c | 90 ++++++++++++++++++-
calendar/libedata-cal/e-cal-backend-store.h | 33 +++++++-
calendar/libedata-cal/e-cal-backend-sync.c | 9 ++
calendar/libedata-cal/e-cal-backend.c | 9 ++
calendar/libedata-cal/e-cal-backend.h | 39 +++++++++
calendar/libedata-cal/e-data-cal-factory.c | 10 ++
calendar/libedata-cal/e-data-cal-view.c | 12 +++
calendar/libedata-cal/e-data-cal.c | 9 ++
24 files changed, 488 insertions(+), 40 deletions(-)
---
diff --git a/calendar/libecal/e-cal-client-view.c b/calendar/libecal/e-cal-client-view.c
index e37f15b..39475f6 100644
--- a/calendar/libecal/e-cal-client-view.c
+++ b/calendar/libecal/e-cal-client-view.c
@@ -21,6 +21,16 @@
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
*/
+/**
+ * SECTION: e-cal-client-view
+ * @include: libecal/libecal.h
+ * @short_description: Recieving change notifications on calendars
+ *
+ * This class provides functionality for watching for changes on a
+ * given calendar opened with an #ECalClient. Use e_cal_client_get_view()
+ * to create an #ECalClientView.
+ **/
+
#ifdef HAVE_CONFIG_H
#include <config.h>
#endif
@@ -740,18 +750,28 @@ e_cal_client_view_class_init (ECalClientViewClass *class)
object_class->dispose = cal_client_view_dispose;
object_class->finalize = cal_client_view_finalize;
+ /**
+ * ECalClientView:client:
+ *
+ * The ECalClient for the view
+ */
g_object_class_install_property (
object_class,
PROP_CLIENT,
g_param_spec_object (
"client",
+ "Client",
"The ECalClient for the view",
- NULL,
E_TYPE_CAL_CLIENT,
G_PARAM_READWRITE |
G_PARAM_CONSTRUCT_ONLY |
G_PARAM_STATIC_STRINGS));
+ /**
+ * ECalClientView:connection:
+ *
+ * The GDBusConnection used to create the D-Bus proxy
+ */
g_object_class_install_property (
object_class,
PROP_CONNECTION,
@@ -765,6 +785,11 @@ e_cal_client_view_class_init (ECalClientViewClass *class)
G_PARAM_CONSTRUCT_ONLY |
G_PARAM_STATIC_STRINGS));
+ /**
+ * ECalClientView:object-path:
+ *
+ * The object path used to create the D-Bus proxy
+ */
g_object_class_install_property (
object_class,
PROP_OBJECT_PATH,
diff --git a/calendar/libecal/e-cal-client.c b/calendar/libecal/e-cal-client.c
index 1989117..17c6779 100644
--- a/calendar/libecal/e-cal-client.c
+++ b/calendar/libecal/e-cal-client.c
@@ -19,6 +19,15 @@
*
*/
+/**
+ * SECTION: e-cal-client
+ * @include: libecal/libecal.h
+ * @short_description: Accessing and modifying a calendar
+ *
+ * This class is the main user facing API for accessing and modifying
+ * the calendar.
+ **/
+
#ifdef HAVE_CONFIG_H
#include <config.h>
#endif
diff --git a/calendar/libecal/e-cal-client.h b/calendar/libecal/e-cal-client.h
index 4e70633..abfbc86 100644
--- a/calendar/libecal/e-cal-client.h
+++ b/calendar/libecal/e-cal-client.h
@@ -508,13 +508,13 @@ gboolean e_cal_client_add_timezone_sync (ECalClient *client,
GCancellable *cancellable,
GError **error);
-#ifndef E_CAL_DISABLE_DEPRECATED
+#ifndef EDS_DISABLE_DEPRECATED
ECalClient * e_cal_client_new (ESource *source,
ECalClientSourceType source_type,
GError **error);
GError * e_cal_client_error_create (ECalClientError code,
const gchar *custom_msg);
-#endif /* E_CAL_DISABLE_DEPRECATED */
+#endif /* EDS_DISABLE_DEPRECATED */
G_END_DECLS
diff --git a/calendar/libecal/e-cal-component.c b/calendar/libecal/e-cal-component.c
index 538488c..d60861f 100644
--- a/calendar/libecal/e-cal-component.c
+++ b/calendar/libecal/e-cal-component.c
@@ -18,6 +18,15 @@
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
*/
+/**
+ * SECTION:e-cal-component
+ * @short_description: A convenience interface for interacting with events
+ * @include: libebook-contacts/libebook-contacts.h
+ *
+ * This is the main user facing interface used for representing an event
+ * or other component in a given calendar.
+ **/
+
#include <config.h>
#include <string.h>
#include <stdlib.h>
@@ -3238,9 +3247,10 @@ e_cal_component_get_exrule_list (ECalComponent *comp,
* e_cal_component_get_exrule_property_list:
* @comp: A calendar component object.
* @recur_list: (out) (transfer none) (element-type icalrecurrencetype):
- * Returns a list of exception rule properties
*
* Queries the list of exception rule properties of a calendar component object.
+ *
+ * Returns: a list of exception rule properties
**/
void
e_cal_component_get_exrule_property_list (ECalComponent *comp,
diff --git a/calendar/libecal/e-cal-system-timezone.c b/calendar/libecal/e-cal-system-timezone.c
index 78767ca..10629f2 100644
--- a/calendar/libecal/e-cal-system-timezone.c
+++ b/calendar/libecal/e-cal-system-timezone.c
@@ -911,12 +911,15 @@ system_timezone_win32_query_registry (void)
/**
* e_cal_system_timezone_get_location:
*
- * Returns system timezone location string, NULL on an error.
- * Returned pointer should be freed with g_free().
+ * Fetches the system timezone location string.
*
* Note: Since 3.4 the returned timezone location is either NULL or
* an equivalent within known libical timezones.
*
+ * The returned string should be freed with g_free().
+ *
+ * Returns: (transfer full): system timezone location string, or %NULL on an error.
+ *
* Since: 2.28
**/
gchar *
diff --git a/calendar/libecal/e-cal-types.h b/calendar/libecal/e-cal-types.h
index a51e457..a496dee 100644
--- a/calendar/libecal/e-cal-types.h
+++ b/calendar/libecal/e-cal-types.h
@@ -32,8 +32,11 @@ G_BEGIN_DECLS
/**
* ECalClientSourceType:
+ * @E_CAL_CLIENT_SOURCE_TYPE_EVENTS: Events calander
+ * @E_CAL_CLIENT_SOURCE_TYPE_TASKS: Task list calendar
+ * @E_CAL_CLIENT_SOURCE_TYPE_MEMOS: Memo list calendar
*
- * FIXME: Document me!
+ * Indicates the type of calendar
*
* Since: 3.2
**/
@@ -46,8 +49,13 @@ typedef enum {
/**
* ECalObjModType:
+ * @E_CAL_OBJ_MOD_THIS: Modify this component
+ * @E_CAL_OBJ_MOD_THIS_AND_PRIOR: Modify this component and all prior occurrances
+ * @E_CAL_OBJ_MOD_THIS_AND_FUTURE: Modify this component and all future occurrances
+ * @E_CAL_OBJ_MOD_ALL: Modify all occurrances of this component
+ * @E_CAL_OBJ_MOD_ONLY_THIS: Modify only this component
*
- * FIXME Document me!
+ * Indicates the type of modification made to a calendar
*
* Since: 3.8
**/
@@ -63,10 +71,27 @@ typedef enum {
#ifndef EDS_DISABLE_DEPRECATED
+/**
+ * E_CALENDAR_ERROR:
+ *
+ * The error domain for the deprecated #ECal
+ *
+ * Deprecated: 3.2: Use #ECalClient and it's errors instead
+ */
#define E_CALENDAR_ERROR e_calendar_error_quark()
GQuark e_calendar_error_quark (void) G_GNUC_CONST;
+/**
+ * ECalChangeType:
+ * @E_CAL_CHANGE_ADDED: A component was added
+ * @E_CAL_CHANGE_MODIFIED: A component was modified
+ * @E_CAL_CHANGE_DELETED: A component was deleted
+ *
+ * Indicates the type of change in an #ECalChange
+ *
+ * Deprecated: 3.2: Use #ECalClient instead
+ */
typedef enum {
E_CAL_CHANGE_ADDED = 1 << 0,
E_CAL_CHANGE_MODIFIED = 1 << 1,
@@ -75,17 +100,31 @@ typedef enum {
/**
* ECalChange:
+ * @comp: The #ECalComponent which changed
+ * @type: The #ECalChangeType which occurred
*
- * FIXME Document me!
+ * A structure indicating a calendar change
*
- * Since: 3.6
+ * Deprecated: 3.2: Use #ECalClient instead
**/
typedef struct {
ECalComponent *comp;
ECalChangeType type;
} ECalChange;
+/**
+ * ECalendarStatus:
+ *
+ * Error codes for the #E_CALENDAR_ERROR error domain
+ *
+ * Deprecated: 3.2: Use #ECalClient and it's errors instead
+ */
+/*
+ * Marked all these deprecated errors as private to avoid
+ * warnings from gtk-doc
+ */
typedef enum {
+ /*< private >*/
E_CALENDAR_STATUS_OK,
E_CALENDAR_STATUS_INVALID_ARG,
E_CALENDAR_STATUS_BUSY,
@@ -109,16 +148,24 @@ typedef enum {
E_CALENDAR_STATUS_NOT_SUPPORTED
} ECalendarStatus;
+/**
+ * E_CALENDAR_STATUS_CORBA_EXCEPTION:
+ *
+ * A deprecated #ECalendarStatus error code
+ *
+ * Deprecated: Use #ECalClient and it's errors instead
+ */
#define E_CALENDAR_STATUS_CORBA_EXCEPTION E_CALENDAR_STATUS_DBUS_EXCEPTION
/**
* EDataCalObjType:
*
- * FIXME Document me!
+ * A deprecated object type indicator
*
- * Since: 3.6
+ * Deprecated
**/
typedef enum {
+ /*< private >*/
Event = 1 << 0,
Todo = 1 << 1,
Journal = 1 << 2,
@@ -128,11 +175,12 @@ typedef enum {
/**
* EDataCalObjModType:
*
- * FIXME Document me!
+ * A deprecated object modification type indicator
*
- * Since: 3.6
+ * Deprecated
**/
typedef enum {
+ /*< private >*/
This = 1 << 0,
ThisAndPrior = 1 << 1,
ThisAndFuture = 1 << 2,
diff --git a/calendar/libecal/e-cal-util.c b/calendar/libecal/e-cal-util.c
index 36b3dcc..03cbb01 100644
--- a/calendar/libecal/e-cal-util.c
+++ b/calendar/libecal/e-cal-util.c
@@ -1182,8 +1182,9 @@ e_cal_util_remove_instances (icalcomponent *icalcomp,
/**
* e_cal_util_get_system_timezone_location:
*
- * Returns system timezone location string, NULL on an error.
- * Returned pointer should be freed with g_free().
+ * Fetches system timezone localtion string.
+ *
+ * Returns: (transfer full): system timezone location string, %NULL on an error.
*
* Since: 2.28
**/
@@ -1196,8 +1197,11 @@ e_cal_util_get_system_timezone_location (void)
/**
* e_cal_util_get_system_timezone:
*
- * Returns icaltimezone object of the system timezone. NULL on an error.
- * Returned pointer is part of the built-in timezones, thus do not free it.
+ * Fetches system timezone icaltimezone object.
+ *
+ * The returned pointer is part of the built-in timezones and should not be freed.
+ *
+ * Returns: (transfer none): The icaltimezone object of the system timezone, or %NULL on an error.
*
* Since: 2.28
**/
@@ -1243,12 +1247,12 @@ componenttime_to_utc_timet (const ECalComponentDateTime *dt_time,
/**
* e_cal_util_get_component_occur_times:
* @comp: an #ECalComponent
- * @start: (out):
- * @end: (out):
- * @tz_cb: (closure tz_cb_data) (scope call):
- * @tz_cb_data: (closure):
- * @default_timezone:
- * @kind:
+ * @start: (out): Location to store the start time
+ * @end: (out): Location to store the end time
+ * @tz_cb: (closure tz_cb_data) (scope call): The #ECalRecurResolveTimezoneFn to call
+ * @tz_cb_data: (closure): User data to be passed to the @tz_cb callback
+ * @default_timezone: The default timezone
+ * @kind: the type of component, indicated with an icalcomponent_kind
*
* Find out when the component starts and stops, being careful about
* recurrences.
diff --git a/calendar/libecal/e-cal.h b/calendar/libecal/e-cal.h
index 6b1b0ad..78606ac 100644
--- a/calendar/libecal/e-cal.h
+++ b/calendar/libecal/e-cal.h
@@ -53,21 +53,50 @@ typedef struct _ECal ECal;
typedef struct _ECalClass ECalClass;
typedef struct _ECalPrivate ECalPrivate;
+/**
+ * ECalSourceType:
+ * @E_CAL_SOURCE_TYPE_EVENT: Event calander
+ * @E_CAL_SOURCE_TYPE_TODO: Todo list calendar
+ * @E_CAL_SOURCE_TYPE_JOURNAL: Journal calendar
+ *
+ * Indicates the type of calendar
+ *
+ * Deprecated: 3.2: Use #ECalClient instead
+ */
typedef enum {
E_CAL_SOURCE_TYPE_EVENT,
E_CAL_SOURCE_TYPE_TODO,
E_CAL_SOURCE_TYPE_JOURNAL,
+ /*< private >*/
E_CAL_SOURCE_TYPE_LAST
} ECalSourceType;
-/* Set mode status for the e_cal_set_mode function */
+/**
+ * ECalSetModeStatus:
+ * @E_CAL_SET_MODE_SUCCESS: Success
+ * @E_CAL_SET_MODE_ERROR: Error
+ * @E_CAL_SET_MODE_NOT_SUPPORTED: Not supported
+ *
+ * Status of e_cal_set_mode() function
+ *
+ * Deprecated: 3.2: Use #ECalClient instead
+ */
typedef enum {
E_CAL_SET_MODE_SUCCESS,
E_CAL_SET_MODE_ERROR,
E_CAL_SET_MODE_NOT_SUPPORTED
} ECalSetModeStatus;
-/* Whether the ecal is not loaded, is being loaded, or is already loaded */
+/**
+ * ECalLoadState:
+ * @E_CAL_LOAD_NOT_LOADED: Not loaded
+ * @E_CAL_LOAD_LOADING: Loading
+ * @E_CAL_LOAD_LOADED: Loaded
+ *
+ * The current loading state reported by e_cal_get_load_state()
+ *
+ * Deprecated: 3.2: Use #ECalClient instead
+ */
typedef enum {
E_CAL_LOAD_NOT_LOADED,
E_CAL_LOAD_LOADING,
@@ -77,28 +106,47 @@ typedef enum {
/**
* EDataCalMode:
*
- * FIXME: Document me.
+ * A deprecated detail of the old #ECal API.
*
- * Since: 3.2
+ * Deprecated: 3.2: Use #ECalClient instead
**/
typedef enum {
+ /*< private >*/
Local = 1 << 0,
Remote = 1 << 1,
AnyMode = 0x07
} EDataCalMode;
+/**
+ * ECal:
+ *
+ * The deprecated API for accessing the calendar
+ *
+ * Deprecated: 3.2: Use #ECalClient instead
+ */
struct _ECal {
- GObject object;
-
/*< private >*/
+ GObject object;
ECalPrivate *priv;
};
+/**
+ * ECalClass:
+ *
+ * Class structure for the deprecated API for accessing the calendar
+ *
+ * Deprecated: 3.2: Use #ECalClient instead
+ */
struct _ECalClass {
+ /*< private >*/
GObjectClass parent_class;
- /* Notification signals */
+ /*
+ * Leaving the whole thing < private >, avoid documenting
+ * the deprecated vfuncs here
+ */
+ /* Notification signals */
#ifndef EDS_DISABLE_DEPRECATED
void (* cal_opened) (ECal *ecal, ECalendarStatus status);
#endif
diff --git a/calendar/libedata-cal/e-cal-backend-cache.c b/calendar/libedata-cal/e-cal-backend-cache.c
index 24b59f9..9c0182e 100644
--- a/calendar/libedata-cal/e-cal-backend-cache.c
+++ b/calendar/libedata-cal/e-cal-backend-cache.c
@@ -19,6 +19,14 @@
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
*/
+/**
+ * SECTION: e-cal-backend-cache
+ * @include: libedata-cal/libedata-cal.h
+ * @short_description: A helper class for caching calendar components
+ *
+ * This class can be used by backends to store calendar components.
+ **/
+
#ifdef HAVE_CONFIG_H
#include <config.h>
#endif
@@ -650,8 +658,9 @@ e_cal_backend_cache_put_key_value (ECalBackendCache *cache,
/**
* e_cal_backend_cache_get_key_value:
* @cache: An #ECalBackendCache object.
+ * @key: The key to fetch a value for
*
- * Returns: The value.
+ * Returns: (transfer none): The value.
*/
const gchar *
e_cal_backend_cache_get_key_value (ECalBackendCache *cache,
@@ -671,6 +680,10 @@ e_cal_backend_cache_get_key_value (ECalBackendCache *cache,
/**
* e_cal_backend_cache_remove:
+ * @dirname: The directory name where the cache is stored
+ * @basename: The directory inside @dirname where the cache is stored
+ *
+ * Removes the cache directory
*
* Since: 2.28
**/
diff --git a/calendar/libedata-cal/e-cal-backend-cache.h b/calendar/libedata-cal/e-cal-backend-cache.h
index 6070133..82a3da9 100644
--- a/calendar/libedata-cal/e-cal-backend-cache.h
+++ b/calendar/libedata-cal/e-cal-backend-cache.h
@@ -54,12 +54,25 @@ typedef struct _ECalBackendCache ECalBackendCache;
typedef struct _ECalBackendCacheClass ECalBackendCacheClass;
typedef struct _ECalBackendCachePrivate ECalBackendCachePrivate;
+/**
+ * ECalBackendCache:
+ *
+ * Contains only private data that should be read and manipulated using the
+ * functions below.
+ */
struct _ECalBackendCache {
+ /*< private >*/
EFileCache parent;
ECalBackendCachePrivate *priv;
};
+/**
+ * ECalBackendCacheClass:
+ *
+ * Class structure for the #ECalBackendCache.
+ */
struct _ECalBackendCacheClass {
+ /*< private >*/
EFileCacheClass parent_class;
};
diff --git a/calendar/libedata-cal/e-cal-backend-factory.c b/calendar/libedata-cal/e-cal-backend-factory.c
index 3a5981c..30d1a8e 100644
--- a/calendar/libedata-cal/e-cal-backend-factory.c
+++ b/calendar/libedata-cal/e-cal-backend-factory.c
@@ -7,6 +7,15 @@
* Copyright (C) 1999-2008 Novell, Inc. (www.novell.com)
*/
+/**
+ * SECTION: e-cal-backend-factory
+ * @include: libedata-cal/libedata-cal.h
+ * @short_description: The factory for creating new calendars
+ *
+ * This class handles creation of new calendars of various
+ * backend types.
+ **/
+
#include <config.h>
#include <string.h>
diff --git a/calendar/libedata-cal/e-cal-backend-factory.h b/calendar/libedata-cal/e-cal-backend-factory.h
index e030dd0..2170f7d 100644
--- a/calendar/libedata-cal/e-cal-backend-factory.h
+++ b/calendar/libedata-cal/e-cal-backend-factory.h
@@ -55,14 +55,35 @@ typedef struct _ECalBackendFactory ECalBackendFactory;
typedef struct _ECalBackendFactoryClass ECalBackendFactoryClass;
typedef struct _ECalBackendFactoryPrivate ECalBackendFactoryPrivate;
+/**
+ * ECalBackendFactory:
+ *
+ * Contains only private data that should be read and manipulated using the
+ * functions below.
+ */
struct _ECalBackendFactory {
+ /*< private >*/
EBackendFactory parent;
ECalBackendFactoryPrivate *priv;
};
+/**
+ * ECalBackendFactoryClass:
+ * @factory_name: The string identifier for this book backend type
+ * @component_kind: The type if component this calendar backend should be created for
+ * @backend_type: The #GType to use to build #EBookBackends for this factory
+ *
+ * Class structure for the #ECalBackendFactory class.
+ *
+ * Subclasses need to set the factory name and backend type
+ * at initialization, the base class will take care of creating
+ * backends of the specified type on demand.
+ */
struct _ECalBackendFactoryClass {
+ /*< private >*/
EBackendFactoryClass parent_class;
+ /*< public >*/
/* Subclasses just need to set these
* class members, we handle the rest. */
const gchar *factory_name;
diff --git a/calendar/libedata-cal/e-cal-backend-intervaltree.c
b/calendar/libedata-cal/e-cal-backend-intervaltree.c
index 8ef66e5..5222a5a 100644
--- a/calendar/libedata-cal/e-cal-backend-intervaltree.c
+++ b/calendar/libedata-cal/e-cal-backend-intervaltree.c
@@ -20,6 +20,18 @@
*
*/
+/**
+ * SECTION: e-cal-backend-intervaltree
+ * @include: libedata-cal/libedata-cal.h
+ * @short_description: A utility for calculating intervals and recurrances
+ *
+ * Implementation of the interval node as described in Introduction to
+ * Algorithms book by Cormen et al, chapter 14.3.
+ *
+ * Basically, the interval tree is the red-black tree, the node key is
+ * the start of the interval.
+ */
+
#ifdef HAVE_CONFIG_H
#include <config.h>
#endif
@@ -569,6 +581,8 @@ e_intervaltree_insert (EIntervalTree *tree,
/**
* e_intervaltree_remove:
* @tree: an #EIntervalTree
+ * @uid: the uid of the component to remove
+ * @rid: the recurrance id of the component to remove
*
* Since: 2.32
**/
@@ -662,7 +676,7 @@ e_intervaltree_remove (EIntervalTree *tree,
* @start: start of the interval
* @end: end of the interval
*
- * Returns list of nodes that overlaps given interval or %NULL.
+ * Returns: list of nodes that overlaps given interval or %NULL.
*
* Since: 2.32
**/
diff --git a/calendar/libedata-cal/e-cal-backend-intervaltree.h
b/calendar/libedata-cal/e-cal-backend-intervaltree.h
index 412be30..b83f7eb 100644
--- a/calendar/libedata-cal/e-cal-backend-intervaltree.h
+++ b/calendar/libedata-cal/e-cal-backend-intervaltree.h
@@ -68,14 +68,26 @@ typedef struct _EIntervalTreePrivate EIntervalTreePrivate;
/**
* EIntervalTree:
*
+ * Contains only private data that should be read and manipulated using the
+ * functions below.
+ *
* Since: 2.32
**/
struct _EIntervalTree {
+ /*< private >*/
GObject parent;
EIntervalTreePrivate *priv;
};
+/**
+ * EIntervalTreeClass:
+ *
+ * Class structure for the #EIntervalTree class.
+ *
+ * Since: 2.32
+ */
struct _EIntervalTreeClass {
+ /*< private >*/
GObjectClass parent_class;
};
diff --git a/calendar/libedata-cal/e-cal-backend-sexp.c b/calendar/libedata-cal/e-cal-backend-sexp.c
index bfe3fd1..78f85ad 100644
--- a/calendar/libedata-cal/e-cal-backend-sexp.c
+++ b/calendar/libedata-cal/e-cal-backend-sexp.c
@@ -18,6 +18,15 @@
* 02110-1301, USA.
*/
+/**
+ * SECTION: e-cal-backend-sexp
+ * @include: libedata-cal/libedata-cal.h
+ * @short_description: A utility for comparing #ECalComponents with search expressions.
+ *
+ * This API is an all purpose utility for comparing #ECalComponents with search expressions
+ * and is used by various backends to implement component filtering and searching.
+ */
+
#ifdef HAVE_CONFIG_H
#include <config.h>
#endif
diff --git a/calendar/libedata-cal/e-cal-backend-sexp.h b/calendar/libedata-cal/e-cal-backend-sexp.h
index 2eb3910..f94d192 100644
--- a/calendar/libedata-cal/e-cal-backend-sexp.h
+++ b/calendar/libedata-cal/e-cal-backend-sexp.h
@@ -55,12 +55,25 @@ typedef struct _ECalBackendSExp ECalBackendSExp;
typedef struct _ECalBackendSExpClass ECalBackendSExpClass;
typedef struct _ECalBackendSExpPrivate ECalBackendSExpPrivate;
+/**
+ * ECalBackendSexp:
+ *
+ * Contains only private data that should be read and manipulated using the
+ * functions below.
+ */
struct _ECalBackendSExp {
+ /*< private >*/
GObject parent;
ECalBackendSExpPrivate *priv;
};
+/**
+ * ECalBackendSexpClass:
+ *
+ * Class structure for the #ECalBackendSexp class.
+ */
struct _ECalBackendSExpClass {
+ /*< private >*/
GObjectClass parent_class;
};
diff --git a/calendar/libedata-cal/e-cal-backend-store.c b/calendar/libedata-cal/e-cal-backend-store.c
index 5296713..d868a97 100644
--- a/calendar/libedata-cal/e-cal-backend-store.c
+++ b/calendar/libedata-cal/e-cal-backend-store.c
@@ -19,6 +19,14 @@
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
*/
+/**
+ * SECTION: e-cal-backend-store
+ * @include: libedata-cal/libedata-cal.h
+ * @short_description: A helper class for storing calendar components
+ *
+ * This class can be used by backends to store calendar components.
+ **/
+
#include "e-cal-backend-store.h"
#include <string.h>
@@ -988,18 +996,28 @@ e_cal_backend_store_class_init (ECalBackendStoreClass *class)
class->get_components = cal_backend_store_get_components;
class->get_component_ids = cal_backend_store_get_component_ids;
+ /**
+ * ECalBackendStore:path:
+ *
+ * The directory to store the file.
+ */
g_object_class_install_property (
object_class,
PROP_PATH,
g_param_spec_string (
"path",
- NULL,
- NULL,
+ "Path",
+ "The directory to store the file",
NULL,
G_PARAM_READWRITE |
G_PARAM_CONSTRUCT_ONLY |
G_PARAM_STATIC_STRINGS));
+ /**
+ * ECalBackendStore:timezone-cache:
+ *
+ * An object implementing the ETimezoneCache interface.
+ */
g_object_class_install_property (
object_class,
PROP_TIMEZONE_CACHE,
@@ -1058,6 +1076,7 @@ e_cal_backend_store_new (const gchar *path,
/**
* e_cal_backend_store_get_path:
+ * @store: an #ECalBackendStore
*
* Since: 2.28
**/
@@ -1092,6 +1111,7 @@ e_cal_backend_store_ref_timezone_cache (ECalBackendStore *store)
/**
* e_cal_backend_store_load:
+ * @store: an #ECalBackendStore
*
* Since: 2.28
**/
@@ -1115,6 +1135,7 @@ e_cal_backend_store_load (ECalBackendStore *store)
/**
* e_cal_backend_store_clean:
+ * @store: an #ECalBackendStore
*
* Since: 2.28
**/
@@ -1138,6 +1159,13 @@ e_cal_backend_store_clean (ECalBackendStore *store)
/**
* e_cal_backend_store_get_component:
+ * @store: an #ECalBackendStore
+ * @uid: the uid of the component to fetch
+ * @rid: the recurrence id of the component to fetch
+ *
+ * Fetches a component by @uid and @rid
+ *
+ * Returns: An #ECalComponent
*
* Since: 2.28
**/
@@ -1159,6 +1187,11 @@ e_cal_backend_store_get_component (ECalBackendStore *store,
/**
* e_cal_backend_store_has_component:
+ * @store: an #ECalBackendStore
+ * @uid: the uid of the component to check
+ * @rid: the recurrence id of the component to check
+ *
+ * Returns: Whether there was a component for @uid and @rid
*
* Since: 2.28
**/
@@ -1180,6 +1213,12 @@ e_cal_backend_store_has_component (ECalBackendStore *store,
/**
* e_cal_backend_store_put_component_with_time_range:
+ * @store: an #ECalBackendStore
+ * @comp: the #ECalComonent to add
+ * @occurence_start: start time of this component
+ * @occurence_end: end time of this component
+ *
+ * Returns: whether @comp was successfully added
*
* Since: 2.32
**/
@@ -1210,6 +1249,10 @@ e_cal_backend_store_put_component_with_time_range (ECalBackendStore *store,
/**
* e_cal_backend_store_put_component:
+ * @store: an #ECalBackendStore
+ * @comp: the #ECalComonent to add
+ *
+ * Returns: whether @comp was successfully added
*
* Since: 2.28
**/
@@ -1230,6 +1273,11 @@ e_cal_backend_store_put_component (ECalBackendStore *store,
/**
* e_cal_backend_store_remove_component:
+ * @store: an #ECalBackendStore
+ * @uid: the uid of the component to remove
+ * @rid: the recurrence id of the component to remove
+ *
+ * Returns: whether the component was successfully removed
*
* Since: 2.28
**/
@@ -1256,6 +1304,11 @@ e_cal_backend_store_remove_component (ECalBackendStore *store,
/**
* e_cal_backend_store_get_default_timezone:
+ * @store: an #ECalBackendStore
+ *
+ * Fetch the default timezone
+ *
+ * Returns: (transfer none): The default timezone
*
* Since: 2.28
**/
@@ -1274,6 +1327,10 @@ e_cal_backend_store_get_default_timezone (ECalBackendStore *store)
/**
* e_cal_backend_store_set_default_timezone:
+ * @store: an #ECalBackendStore
+ * @zone: the timezone to set
+ *
+ * Returns: whether the timezone was successfully set
*
* Since: 2.28
**/
@@ -1294,6 +1351,10 @@ e_cal_backend_store_set_default_timezone (ECalBackendStore *store,
/**
* e_cal_backend_store_get_components_by_uid:
+ * @store: an #ECalBackendStore
+ * @uid: the @uid of the components to fetch
+ *
+ * Returns: a list of components matching @uid
*
* Since: 2.28
**/
@@ -1366,6 +1427,9 @@ e_cal_backend_store_get_components_by_uid_as_ical_string (ECalBackendStore *stor
/**
* e_cal_backend_store_get_components:
+ * @store: an #ECalBackendStore
+ *
+ * Returns: the list of components in @store
*
* Since: 2.28
**/
@@ -1385,13 +1449,13 @@ e_cal_backend_store_get_components (ECalBackendStore *store)
/**
* e_cal_backend_store_get_components_occuring_in_range:
* @store: An #ECalBackendStore object.
- * @start:
- * @end:
+ * @start: Start time
+ * @end: End time
*
* Retrieves a list of components stored in the store, that are occuring
* in time range [start, end].
*
- * Return value: A list of the components. Each item in the list is
+ * Returns: (transfer full): A list of the components. Each item in the list is
* an #ECalComponent, which should be freed when no longer needed.
*
* Since: 2.32
@@ -1438,6 +1502,7 @@ e_cal_backend_store_get_components_occuring_in_range (ECalBackendStore *store,
/**
* e_cal_backend_store_get_component_ids:
+ * @store: an #ECalBackendStore
*
* Since: 2.28
**/
@@ -1456,6 +1521,10 @@ e_cal_backend_store_get_component_ids (ECalBackendStore *store)
/**
* e_cal_backend_store_get_key_value:
+ * @store: an #ECalBackendStore
+ * @key: the key for the value to fetch
+ *
+ * Returns: (transfer none): The value matching @key
*
* Since: 2.28
**/
@@ -1476,6 +1545,11 @@ e_cal_backend_store_get_key_value (ECalBackendStore *store,
/**
* e_cal_backend_store_put_key_value:
+ * @store: an #ECalBackendStore
+ * @key: the key for the value to set
+ * @value: the value to set for @key
+ *
+ * Returns: whether @value was successfully set for @key
*
* Since: 2.28
**/
@@ -1497,6 +1571,7 @@ e_cal_backend_store_put_key_value (ECalBackendStore *store,
/**
* e_cal_backend_store_thaw_changes:
+ * @store: an #ECalBackendStore
*
* Since: 2.28
**/
@@ -1515,6 +1590,7 @@ e_cal_backend_store_thaw_changes (ECalBackendStore *store)
/**
* e_cal_backend_store_freeze_changes:
+ * @store: an #ECalBackendStore
*
* Since: 2.28
**/
@@ -1533,6 +1609,10 @@ e_cal_backend_store_freeze_changes (ECalBackendStore *store)
/**
* e_cal_backend_store_interval_tree_add_comp:
+ * @store: an #ECalBackendStore
+ * @comp: the #ECalComponent to add
+ * @occurence_start: start time for @comp
+ * @occurence_end: end time for @comp
*
* Since: 2.32
**/
diff --git a/calendar/libedata-cal/e-cal-backend-store.h b/calendar/libedata-cal/e-cal-backend-store.h
index 79152fd..55b781a 100644
--- a/calendar/libedata-cal/e-cal-backend-store.h
+++ b/calendar/libedata-cal/e-cal-backend-store.h
@@ -56,16 +56,45 @@ typedef struct _ECalBackendStorePrivate ECalBackendStorePrivate;
/**
* ECalBackendStore:
*
+ * Contains only private data that should be read and manipulated using the
+ * functions below.
+ *
* Since: 2.28
**/
struct _ECalBackendStore {
+ /*< private >*/
GObject parent;
ECalBackendStorePrivate *priv;
};
+/**
+ * ECalBackendStoreClass:
+ * @load: FIXME: Doxument me
+ * @clean: FIXME: Doxument me
+ * @get_component: FIXME: Doxument me
+ * @put_component: FIXME: Doxument me
+ * @remove_component: FIXME: Doxument me
+ * @has_component: FIXME: Doxument me
+ * @get_components_by_uid: FIXME: Doxument me
+ * @get_components: FIXME: Doxument me
+ * @get_component_ids: FIXME: Doxument me
+ * @get_default_timezone: FIXME: Doxument me
+ * @set_default_timezone: FIXME: Doxument me
+ * @thaw_changes: FIXME: Doxument me
+ * @freeze_changes: FIXME: Doxument me
+ * @get_key_value: FIXME: Doxument me
+ * @put_key_value: FIXME: Doxument me
+ *
+ * Class structure for the #ECalBackendStore class.
+ *
+ * Since: 2.28
+ */
struct _ECalBackendStoreClass {
+ /*< private >*/
GObjectClass parent_class;
+ /*< public >*/
+
/* virtual methods */
gboolean (*load) (ECalBackendStore *store);
gboolean (*clean) (ECalBackendStore *store);
@@ -162,8 +191,8 @@ void e_cal_backend_store_freeze_changes
void e_cal_backend_store_interval_tree_add_comp
(ECalBackendStore *store,
ECalComponent *comp,
- time_t start,
- time_t end);
+ time_t occurence_start,
+ time_t occurence_end);
G_END_DECLS
diff --git a/calendar/libedata-cal/e-cal-backend-sync.c b/calendar/libedata-cal/e-cal-backend-sync.c
index 6dd5fe1..2158ffe 100644
--- a/calendar/libedata-cal/e-cal-backend-sync.c
+++ b/calendar/libedata-cal/e-cal-backend-sync.c
@@ -6,6 +6,15 @@
* Copyright (C) 1999-2008 Novell, Inc. (www.novell.com)
*/
+/**
+ * SECTION: e-cal-backend-sync
+ * @include: libedata-cal/libedata-cal.h
+ * @short_description: A convenience subclass of #ECalBackend
+ *
+ * This class can be subclassed in place of the #ECalBackend
+ * abstract backend for easier implementation of calendar backends.
+ **/
+
#ifdef HAVE_CONFIG_H
#include <config.h>
#endif
diff --git a/calendar/libedata-cal/e-cal-backend.c b/calendar/libedata-cal/e-cal-backend.c
index e2de8c1..ccd068a 100644
--- a/calendar/libedata-cal/e-cal-backend.c
+++ b/calendar/libedata-cal/e-cal-backend.c
@@ -16,6 +16,15 @@
*
*/
+/**
+ * SECTION: e-cal-backend
+ * @include: libedata-cal/libedata-cal.h
+ * @short_description: An abstract class for implementing calendar backends
+ *
+ * This is the main server facing API for interfacing with calendar backends,
+ * calendar backends must implement methods on this class.
+ **/
+
#include <config.h>
#include <glib/gi18n-lib.h>
diff --git a/calendar/libedata-cal/e-cal-backend.h b/calendar/libedata-cal/e-cal-backend.h
index 7678b58..597b880 100644
--- a/calendar/libedata-cal/e-cal-backend.h
+++ b/calendar/libedata-cal/e-cal-backend.h
@@ -102,14 +102,53 @@ typedef struct _ECalBackend ECalBackend;
typedef struct _ECalBackendClass ECalBackendClass;
typedef struct _ECalBackendPrivate ECalBackendPrivate;
+/**
+ * ECalBackend:
+ *
+ * Contains only private data that should be read and manipulated using the
+ * functions below.
+ */
struct _ECalBackend {
+ /*< private >*/
EBackend parent;
ECalBackendPrivate *priv;
};
+/**
+ * ECalBackendClass:
+ * @use_serial_dispatch_queue: Whether a serial dispatch queue should
+ * be used for this backend or not.
+ * @get_backend_property: Fetch a property value by name from the backend
+ * @open: Open the backend
+ * @refresh: Refresh the backend
+ * @get_object: Fetch a calendar object
+ * @get_object_list: FIXME: Document me
+ * @get_free_busy: FIXME: Document me
+ * @create_objects: FIXME: Document me
+ * @modify_objects: FIXME: Document me
+ * @remove_objects: FIXME: Document me
+ * @receive_objects: FIXME: Document me
+ * @send_objects: FIXME: Document me
+ * @get_attachment_uris: FIXME: Document me
+ * @discard_alarm: FIXME: Document me
+ * @get_timezone: FIXME: Document me
+ * @add_timezone: FIXME: Document me
+ * @start_view: Start up the specified view
+ * @stop_view: Stop the specified view
+ * @closed: A signal notifying that the backend was closed
+ * @shutdown: A signal notifying that the backend is being shut down
+ *
+ * Class structure for the #ECalBackend class.
+ *
+ * These virtual methods must be implemented when writing
+ * a calendar backend.
+ */
struct _ECalBackendClass {
+ /*< private >*/
EBackendClass parent_class;
+ /*< public >*/
+
/* Set this to TRUE to use a serial dispatch queue, instead
* of a concurrent dispatch queue. A serial dispatch queue
* executes one method at a time in the order in which they
diff --git a/calendar/libedata-cal/e-data-cal-factory.c b/calendar/libedata-cal/e-data-cal-factory.c
index 87cdc70..047e6bb 100644
--- a/calendar/libedata-cal/e-data-cal-factory.c
+++ b/calendar/libedata-cal/e-data-cal-factory.c
@@ -23,6 +23,16 @@
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
*/
+/**
+ * SECTION: e-data-cal-factory
+ * @include: libedata-cal/libedata-cal.h
+ * @short_description: The main calendar server object
+ *
+ * This class handles incomming D-Bus connections and creates
+ * the #EDataCal layer for server side calendars to communicate
+ * with client side #ECalClient objects.
+ **/
+
#include <config.h>
#include <locale.h>
#include <stdlib.h>
diff --git a/calendar/libedata-cal/e-data-cal-view.c b/calendar/libedata-cal/e-data-cal-view.c
index 28ff013..7e5abf0 100644
--- a/calendar/libedata-cal/e-data-cal-view.c
+++ b/calendar/libedata-cal/e-data-cal-view.c
@@ -21,6 +21,18 @@
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
*/
+/**
+ * SECTION: e-data-cal-view
+ * @include: libedata-cal/libedata-cal.h
+ * @short_description: A server side object for issuing view notifications
+ *
+ * This class communicates with #ECalClientViews over the bus.
+ *
+ * Calendar backends can automatically own a number of views requested
+ * by the client, this API can be used by the backend to issue notifications
+ * which will be delivered to the #ECalClientView
+ **/
+
#ifdef HAVE_CONFIG_H
#include <config.h>
#endif
diff --git a/calendar/libedata-cal/e-data-cal.c b/calendar/libedata-cal/e-data-cal.c
index 17315b2..eeaf87a 100644
--- a/calendar/libedata-cal/e-data-cal.c
+++ b/calendar/libedata-cal/e-data-cal.c
@@ -16,6 +16,15 @@
*
*/
+/**
+ * SECTION: e-data-cal
+ * @include: libedata-cal/libedata-cal.h
+ * @short_description: Server side D-Bus layer to communicate with calendars
+ *
+ * This class communicates with #ECalClients over the bus and accesses
+ * an #ECalBackend to satisfy client requests.
+ **/
+
#ifdef HAVE_CONFIG_H
#include <config.h>
#endif
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
