docs(caldav): update documentation for calendar search

lib/public/Calendar/ICalendar.php

@@ -8,10 +8,18 @@
  */
 namespace OCP\Calendar;
 
+use DateTimeInterface;
+
 /**
  * Interface ICalendar
  *
  * @since 13.0.0
+ *
+ * @psalm-type CalendarSearchOptions = array{
+ *     timerange?: array{start?: DateTimeInterface, end?: DateTimeInterface},
+ *     uid?: string,
+ *     types?: string[],
+ * }
  */
 interface ICalendar {
 	/**
@@ -41,13 +49,63 @@ public function getDisplayName(): ?string;
 	public function getDisplayColor(): ?string;
 
 	/**
-	 * @param string $pattern which should match within the $searchProperties
-	 * @param array $searchProperties defines the properties within the query pattern should match
-	 * @param array $options - optional parameters:
-	 *                       ['timerange' => ['start' => new DateTime(...), 'end' => new DateTime(...)]]
-	 * @param int|null $limit - limit number of search results
-	 * @param int|null $offset - offset for paging of search results
-	 * @return array an array of events/journals/todos which are arrays of key-value-pairs. the events are sorted by start date (closest first, furthest last)
+	 * Search the current calendar for matching events.
+	 *
+	 * This method searches for events in the calendar that match a given pattern within specified properties.
+	 * The search is case-insensitive. It supports optional parameters such as a time range, limit, and offset.
+	 * The results are sorted by start date, with the closest events appearing first.
+	 *
+	 * @param string $pattern A string to search for within the events. The search is done case-insensitive.
+	 * @param array $searchProperties Defines the properties within which the pattern should match.
+	 * @param array $options Optional parameters for the search:
+	 *                       - 'timerange' element that can have 'start' (DateTimeInterface), 'end' (DateTimeInterface), or both.
+	 *                       - 'uid' element to look for events with a given uid.
+	 *                       - 'types' element to only return events for a given type (e.g. VEVENT or VTODO)
+	 * @psalm-param CalendarSearchOptions $options
+	 * @param int|null $limit Limit the number of search results.
+	 * @param int|null $offset For paging of search results.
+	 * @return array An array of events/journals/todos which are arrays of key-value-pairs. The events are sorted by start date (closest first, furthest last).
+	 *
+	 * Implementation Details:
+	 *
+	 * An event can consist of many sub-events, typically the case for events with recurrence rules. On a database level,
+	 * there's only one event stored (with a matching first occurrence and last occurrence timestamp). Expanding an event
+	 * into sub-events is done on the backend level. Using limit, offset, and timerange comes with some drawbacks.
+	 * When asking the database for events, the result is ordered by the primary key to guarantee a stable order.
+	 * After expanding the events into sub-events, they are sorted by the date (closest to furthest).
+	 *
+	 * Usage Examples:
+	 *
+	 * 1) Find 7 events within the next two weeks:
+	 *
+	 * $dateTime = (new DateTimeImmutable())->setTimestamp($this->timeFactory->getTime());
+	 * $inTwoWeeks = $dateTime->add(new DateInterval('P14D'));
+	 *
+	 * $calendar->search(
+	 *     '',
+	 *     [],
+	 *     ['timerange' => ['start' => $dateTime, 'end' => $inTwoWeeks]],
+	 *     7
+	 * );
+	 *
+	 * Note: When combining timerange and limit, it's possible that the expected outcome is not in the order you would expect.
+	 *
+	 * Example: Create 7 events for tomorrow, starting from 11:00, 30 minutes each. Then create an 8th event for tomorrow at 10:00.
+	 * The above code will list the event at 11:00 first, missing the event at 10:00. The reason is the ordering by the primary key
+	 * and expanding on the backend level. This is a technical limitation. The easiest workaround is to fetch more events
+	 * than you actually need, with the downside of needing more resources.
+	 *
+	 * Related:
+	 * - https://github.com/nextcloud/server/pull/45222
+	 * - https://github.com/nextcloud/server/issues/53002
+	 *
+	 * 2) Find all events where the location property contains the string 'Berlin':
+	 *
+	 * $calendar->search(
+	 *     'Berlin',
+	 *     ['LOCATION']
+	 * );
+	 *
 	 * @since 13.0.0
 	 */
 	public function search(string $pattern, array $searchProperties = [], array $options = [], ?int $limit = null, ?int $offset = null): array;