Improve documentation for some higher level APIs and Todo overview (#292

)

DESIGN.md

@@ -86,6 +86,16 @@ each recurring event. A merged iterator peeks into the input of each
 iterator to decide which one to pull from when determinig the next item
 in the iterator.
 
+An individual instance of a recurring event is generated with the same `UID`,
+but with a different `RECURRENCE_ID` based on the start time of that instance.
+
 ### Recurrence Editing
 
-WIP
+An entire series may be modified by modifying the original event without
+referencing a `RECURRENCE_ID`. A `RECURRENCE_ID` can refer to a specific
+instance in the series, or with `THIS_AND_FUTURE` to apply to forward looking
+events.
+
+When modifying an instance, a new copy of the event is created for that instance
+and the original event representing the whole series is modified to exclude
+the edited instance.

README.md

@@ -63,6 +63,14 @@ with filename.open() as ics_file:
     ics_file.write(IcsCalendarStream.calendar_to_ics(calendar))
 ```
 
+# Application-level APIs
+
+The above APIs are used for lower level interaction with calendar components,
+however applications require a higher level interface to manage some of the
+underlying complexity. The `ical.store` library is used to manage state at a higher
+level (e.g. ensuring timezones are created properly) or handling edits to
+recurring events.
+
 # Recurring events
 
 A calendar event may be recurring (e.g. weekly, monthly, etc). Recurring events

ical/todo.py

@@ -1,4 +1,12 @@
-"""A grouping of component properties that describe a to-do."""
+"""A grouping of component properties that describe a to-do.
+
+A todo component can represent an item of work assigned to an individual
+such as "turn in a travel expense today".
+
+A todo component without a start date or due date (or duration) specifies
+a to-do that will be associated with each successive calendar date until it
+is completed.
+"""
 
 from __future__ import annotations