Add KDoc

Author: rfc2822

lib/src/main/kotlin/at/bitfire/ical4android/AndroidEvent.kt

@@ -786,7 +786,7 @@ class AndroidEvent(
     private fun buildEvent(recurrence: Event?, builder: CpoBuilder) {
         val event = recurrence ?: requireNotNull(event)
 
-        val dtStart = event.dtStart ?: throw LocalStorageException("Events must have DTSTART")
+        val dtStart = event.dtStart ?: throw InvalidLocalResourceException("Events must have DTSTART")
         val allDay = DateUtils.isDate(dtStart)
 
         // make sure that time zone is supported by Android

lib/src/main/kotlin/at/bitfire/ical4android/Event.kt

@@ -253,6 +253,7 @@ data class Event(
          * @throws IOException on I/O errors
          * @throws ParserException when the iCalendar can't be parsed
          */
+        @Deprecated("Use ICalendarParser and CalendarUidSplitter directly")
         fun eventsFromReader(
             reader: Reader,
             properties: MutableMap<String, String>? = null
@@ -277,23 +278,20 @@ data class Event(
 
             // convert into Events (data class)
             val events = mutableListOf<Event>()
-            for ((uid, associatedEvents) in vEventsByUid) {
-                val mainVEvent =
-                    if (associatedEvents.main != null)
-                        associatedEvents.main
-                    else {
-                        logger.info("UID $uid doesn't have a main event but only exceptions; creating fake main event")
-                        associatedEvents.exceptions.first()
-                    }
+            for (associatedEvents in vEventsByUid.values) {
+                val mainVEvent = associatedEvents.main ?:
+                    // no main event but only exceptions, create fake main event
+                    // FIXME: we should construct a valid recurring fake event, not just take the exception
+                    associatedEvents.exceptions.first()
 
                 val event = fromVEvent(mainVEvent)
-                event.exceptions.addAll(associatedEvents.exceptions.map {
-                    fromVEvent(it).also { exception ->
+                for (exceptionVEvent in associatedEvents.exceptions) {
+                    event.exceptions += fromVEvent(exceptionVEvent).also { exception ->
                         // make sure that exceptions have at least a SUMMARY (if the main event does have one)
                         if (exception.summary == null)
                             exception.summary = event.summary
                     }
-                })
+                }
 
                 events += event
             }

lib/src/main/kotlin/at/bitfire/synctools/icalendar/AssociatedComponents.kt

@@ -10,6 +10,16 @@ import net.fortuna.ical4j.model.component.CalendarComponent
 import net.fortuna.ical4j.model.component.VEvent
 
 /**
+ * Represents a set of components (like VEVENT) stored in a calendar object resource as defined
+ * in RFC 4791 section 4.1. It consists of
+ *
+ * - an (optional) main component,
+ * - optional exceptions of this main component.
+ *
+ * Note: It's possible and valid that there's no main component, but only exceptions, for instance
+ * when the user has been invited to a specific instance (= exception) of a recurring event, but
+ * not to the event as a whole (→ main event is unknown / not present).
+ *
  * @param main          main component (with or without UID, but without RECURRENCE-ID), may be `null` if only exceptions are present
  * @param exceptions    exceptions (each without RECURRENCE-ID); UID must be
  *   1. the same as the UID of [main],
@@ -34,6 +44,9 @@ data class AssociatedComponents<T: CalendarComponent>(
      * @throws IllegalArgumentException     if [main] and/or [exceptions] UIDs don't match
      */
     private fun validate() {
+        if (main == null && exceptions.isEmpty())
+            throw IllegalArgumentException("At least one component is required")
+
         val mainUid =
             if (main != null) {
                 if (main.recurrenceId != null)

lib/src/main/kotlin/at/bitfire/synctools/icalendar/CalendarUidSplitter.kt

@@ -10,18 +10,22 @@ import androidx.annotation.VisibleForTesting
 import net.fortuna.ical4j.model.Calendar
 import net.fortuna.ical4j.model.component.CalendarComponent
 
-/**
- * Splits iCalendar components by UID.
- */
 class CalendarUidSplitter<T: CalendarComponent> {
 
+    /**
+     * Splits iCalendar components by UID and classifies them as main events (without RECURRENCE-ID)
+     * or exceptions (with RECURRENCE-ID).
+     *
+     * When there are multiple components with the same UID and RECURRENCE-ID, but different SEQUENCE,
+     * this method keeps only the ones with the highest SEQUENCE.
+     */
     fun associateByUid(calendar: Calendar, componentName: String): Map<String?, AssociatedComponents<T>> {
         // get all components of type T (for instance: all VEVENTs)
-        val allComponents = calendar.getComponents<T>(componentName).toMutableList()
+        val all = calendar.getComponents<T>(componentName)
 
         // Note for VEVENT: UID is REQUIRED in RFC 5545 section 3.6.1, but optional in RFC 2445 section 4.6.1,
         // so it's possible that the Uid is null.
-        val byUid: Map<String?, List<T>> = allComponents
+        val byUid: Map<String?, List<T>> = all
             .groupBy { it.uid?.value }
             .mapValues { filterBySequence(it.value) }
 
@@ -38,9 +42,9 @@ class CalendarUidSplitter<T: CalendarComponent> {
     /**
      * Keeps only the events with the highest SEQUENCE (per RECURRENCE-ID).
      *
-     * @param events    list of VEVENTs with the same UID, but different RECURRENCE-IDs and SEQUENCEs
+     * @param events    list of VEVENTs with the same UID, but different RECURRENCE-IDs (may be `null`) and SEQUENCEs
      *
-     * @return same as input list, but each RECURRENCE-ID event only with the highest SEQUENCE
+     * @return same as input list, but each RECURRENCE-ID occurs only with the highest SEQUENCE
      */
     @VisibleForTesting
     internal fun filterBySequence(events: List<T>): List<T> {

lib/src/main/kotlin/at/bitfire/synctools/icalendar/ICalendarParser.kt

@@ -27,7 +27,7 @@ class ICalendarParser {
         get() = Logger.getLogger(javaClass.name)
 
     /**
-     * Parses the given iCalendar and applies some error correction:
+     * Parses the given iCalendar as lenient as possible and applies some error correction:
      *
      * 1. The input stream from is preprocessed with [ICalPreprocessor.preprocessStream].
      * 2. The parsed calendar is preprocessed with [ICalPreprocessor.preprocessCalendar].

lib/src/test/kotlin/at/bitfire/synctools/icalendar/AssociatedComponentsTest.kt

@@ -14,7 +14,7 @@ import org.junit.Test
 
 class AssociatedComponentsTest {
 
-    @Test
+    @Test(expected = IllegalArgumentException::class)
     fun testEmpty() {
         AssociatedEvents(null, emptyList())
     }