diff --git a/CHANGES.rst b/CHANGES.rst index ea571088..d7d1c88f 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -9,6 +9,7 @@ Minor changes: - Added ``end``, ``start``, ``duration``, ``DTSTART``, ``DUE``, and ``DURATION`` attributes to ``Todo`` components. See `Issue 662`_. - Format test code with Ruff. See `Issue 672 `_. - Document the Debian package. See `Issue 701 `_. +- Document component classes with description from :rfc:`5545`. Breaking changes: diff --git a/src/icalendar/cal.py b/src/icalendar/cal.py index 0649189f..c01925ce 100644 --- a/src/icalendar/cal.py +++ b/src/icalendar/cal.py @@ -591,6 +591,12 @@ def _del_duration(self: Component): class Event(Component): + """ + A "VEVENT" calendar component is a grouping of component + properties that represents a scheduled amount of time on a + calendar. For example, it can be an activity, such as a one-hour + long department meeting from 8:00 AM to 9:00 AM, tomorrow. + """ name = 'VEVENT' @@ -706,6 +712,13 @@ def end(self, end: date | datetime | None): class Todo(Component): + """ + A "VTODO" calendar component is a grouping of component + properties that represents an action item or assignment. For + example, it can be used to represent an item of work assigned to + an individual, such as "Prepare for the upcoming conference + seminar on Internet Calendaring". + """ name = 'VTODO' @@ -863,6 +876,12 @@ def duration(self) -> timedelta: return timedelta(0) class FreeBusy(Component): + """ + A "VFREEBUSY" calendar component is a grouping of component + properties that represents either a request for free or busy time + information, a reply to a request for free or busy time + information, or a published set of busy time information. + """ name = 'VFREEBUSY' @@ -875,6 +894,11 @@ class FreeBusy(Component): class Timezone(Component): + """ + A "VTIMEZONE" calendar component is a grouping of component + properties that defines a time zone. It is used to describe the + way in which a time zone changes its offset from UTC over time. + """ name = 'VTIMEZONE' canonical_order = ('TZID',) required = ('TZID',) # it also requires one of components DAYLIGHT and STANDARD @@ -1035,6 +1059,12 @@ def get_transitions(self) -> Tuple[List[datetime], List[Tuple[timedelta, timedel class TimezoneStandard(Component): + """ + The "STANDARD" sub-component of "VTIMEZONE" defines the standard + time offset from UTC for a time zone. It represents a time zone's + standard time, typically used during winter months in locations + that observe Daylight Saving Time. + """ name = 'STANDARD' required = ('DTSTART', 'TZOFFSETTO', 'TZOFFSETFROM') singletons = ('DTSTART', 'TZOFFSETTO', 'TZOFFSETFROM',) @@ -1042,6 +1072,12 @@ class TimezoneStandard(Component): class TimezoneDaylight(Component): + """ + The "DAYLIGHT" sub-component of "VTIMEZONE" defines the daylight + saving time offset from UTC for a time zone. It represents a time + zone's daylight saving time, typically used during summer months + in locations that observe Daylight Saving Time. + """ name = 'DAYLIGHT' required = TimezoneStandard.required singletons = TimezoneStandard.singletons @@ -1049,6 +1085,12 @@ class TimezoneDaylight(Component): class Alarm(Component): + """ + A "VALARM" calendar component is a grouping of component + properties that defines an alarm or reminder for an event or a + to-do. For example, it may be used to define a reminder for a + pending event or an overdue to-do. + """ name = 'VALARM' # some properties MAY/MUST/MUST NOT appear depending on ACTION value @@ -1062,7 +1104,11 @@ class Alarm(Component): class Calendar(Component): - """This is the base object for an iCalendar file. + """ + The "VCALENDAR" object is a collection of calendar information. + This information can include a variety of components, such as + "VEVENT", "VTODO", "VJOURNAL", "VFREEBUSY", "VTIMEZONE", or any + other type of calendar component. """ name = 'VCALENDAR' canonical_order = ('VERSION', 'PRODID', 'CALSCALE', 'METHOD',)