1 files changed, 48 insertions, 23 deletions

diff --git a/libical/src/libical/icalrecur.h b/libical/src/libical/icalrecur.h
index 5fcdc15..5f6ac55 100644
--- a/libical/src/libical/icalrecur.h
+++ b/libical/src/libical/icalrecur.h
@@ -18,2 +18,7 @@
     the License at http://www.mozilla.org/MPL/
+*/
+
+/**
+@file icalrecur.h
+@brief Routines for dealing with recurring time
 
@@ -22,2 +27,4 @@ How to use:
 1) Get a rule and a start time from a component
+
+@code
         icalproperty rrule;
@@ -29,12 +36,21 @@ How to use:
         start = icalproperty_get_dtstart(dtstart);
+@endcode
 
 Or, just make them up: 
+
+@code
         recur = icalrecurrencetype_from_string("FREQ=YEARLY;BYDAY=SU,WE");
         dtstart = icaltime_from_string("19970101T123000")
+@endcode
 
 2) Create an iterator
+
+@code
         icalrecur_iterator* ritr;
         ritr = icalrecur_iterator_new(recur,start);
+@endcode
 
 3) Iterator over the occurrences
+
+@code
         struct icaltimetype next;
@@ -44,2 +60,3 @@ Or, just make them up:
         }
+@endcode
 
@@ -48,3 +65,3 @@ whatever timezone that dtstart is in.
 
-======================================================================*/
+*/
 
@@ -56,5 +73,5 @@ whatever timezone that dtstart is in.
 
-/***********************************************************************
+/*
  * Recurrance enumerations
-**********************************************************************/
+ */
 
@@ -95,3 +112,5 @@ enum {
 
-/********************** Recurrence type routines **************/
+/**
+ * Recurrence type routines
+ */
 
@@ -110,3 +129,3 @@ enum {
 
-/* Main struct for holding digested recurrence rules */
+/** Main struct for holding digested recurrence rules */
 struct icalrecurrencetype 
@@ -147,19 +166,21 @@ void icalrecurrencetype_clear(struct icalrecurrencetype *r);
 
-/* The 'day' element of the by_day array is encoded to allow
-representation of both the day of the week ( Monday, Tueday), but also
-the Nth day of the week ( First tuesday of the month, last thursday of
-the year) These routines decode the day values */
+/**
+ * Array Encoding
+ *
+ * The 'day' element of the by_day array is encoded to allow
+ * representation of both the day of the week ( Monday, Tueday), but also
+ * the Nth day of the week ( First tuesday of the month, last thursday of
+ * the year) These routines decode the day values 
+ */
 
-/* 1 == Monday, etc. */
+/** 1 == Monday, etc. */
 enum icalrecurrencetype_weekday icalrecurrencetype_day_day_of_week(short day);
 
-/* 0 == any of day of week. 1 == first, 2 = second, -2 == second to last, etc */
-short icalrecurrencetype_day_position(short day);
+/** 0 == any of day of week. 1 == first, 2 = second, -2 == second to last, etc */
+int icalrecurrencetype_day_position(short day);
 
 
-/***********************************************************************
- * Recurrance rule parser
-**********************************************************************/
+/** Recurrance rule parser */
 
-/* Convert between strings ans recurrencetype structures. */
+/** Convert between strings and recurrencetype structures. */
 struct icalrecurrencetype icalrecurrencetype_from_string(const char* str);
@@ -168,7 +189,7 @@ char* icalrecurrencetype_as_string(struct icalrecurrencetype *recur);
 
-/********** recurrence iteration routines ********************/
+/** Recurrence iteration routines */
 
-typedef void icalrecur_iterator;
+typedef struct icalrecur_iterator_impl  icalrecur_iterator;
 
-/* Create a new recurrence rule iterator */
+/** Create a new recurrence rule iterator */
 icalrecur_iterator* icalrecur_iterator_new(struct icalrecurrencetype rule, 
@@ -176,10 +197,14 @@ icalrecur_iterator* icalrecur_iterator_new(struct icalrecurrencetype rule,
 
-/* Get the next occurrence from an iterator */
+/** Get the next occurrence from an iterator */
 struct icaltimetype icalrecur_iterator_next(icalrecur_iterator*);
 
-/* Free the iterator */
+void icalrecur_iterator_decrement_count(icalrecur_iterator*);
+
+/** Free the iterator */
 void icalrecur_iterator_free(icalrecur_iterator*);
 
-/* Fills array up with at most 'count' time_t values, each
-   representing an occurrence time in seconds past the POSIX epoch */
+/**
+ * Fills array up with at most 'count' time_t values, each
+ *  representing an occurrence time in seconds past the POSIX epoch 
+ */
 int icalrecur_expand_recurrence(char* rule, time_t start,