[evolution-data-server/documentation-effort: 15/18] Calendar: Fixing up gtk-doc comments, ensuring main descriptions.

[Tristan Van Berkom <tvb src gnome org>]

commit 9c67bfebf13f34b571c8f0ecad61b6b960ab6057
Author: Tristan Van Berkom <tristan upstairslabs com>
Date:   Thu Dec 5 20:30:00 2013 +0900

    Calendar: Fixing up gtk-doc comments, ensuring main descriptions.

 calendar/libecal/e-cal-client-view.c               |   10 ++++++++++
 calendar/libecal/e-cal-client.c                    |    9 +++++++++
 calendar/libecal/e-cal-component.c                 |    9 +++++++++
 calendar/libedata-cal/e-cal-backend-cache.c        |    8 ++++++++
 calendar/libedata-cal/e-cal-backend-factory.c      |    9 +++++++++
 calendar/libedata-cal/e-cal-backend-intervaltree.c |   12 ++++++++++++
 calendar/libedata-cal/e-cal-backend-sexp.c         |    9 +++++++++
 calendar/libedata-cal/e-cal-backend-store.c        |    8 ++++++++
 calendar/libedata-cal/e-cal-backend-sync.c         |    9 +++++++++
 calendar/libedata-cal/e-cal-backend.c              |    9 +++++++++
 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 +++++++++
 13 files changed, 123 insertions(+), 0 deletions(-)
---
diff --git a/calendar/libecal/e-cal-client-view.c b/calendar/libecal/e-cal-client-view.c
index 447ba37..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
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-component.c b/calendar/libecal/e-cal-component.c
index c87c092..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>
diff --git a/calendar/libedata-cal/e-cal-backend-cache.c b/calendar/libedata-cal/e-cal-backend-cache.c
index 24b59f9..17fd631 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
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-intervaltree.c 
b/calendar/libedata-cal/e-cal-backend-intervaltree.c
index 3564441..15dc85f 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
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-store.c b/calendar/libedata-cal/e-cal-backend-store.c
index 7389878..c508a5a 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>
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-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