Merge pull request #738 from niccokunzmann/rfc-docs

Follow up #730 - rfc 5545 docs on components

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 <https://github.com/collective/icalendar/issues/672>`_.
 - Document the Debian package. See `Issue 701 <https://github.com/collective/icalendar/issues/701>`_.
+- Document component classes with description from :rfc:`5545`.
 
 Breaking changes:
 

src/icalendar/cal.py

@@ -591,6 +591,12 @@ Instead use the duration property (lower case).
 
 
 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 @@ class Event(Component):
 
 
 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 @@ class Journal(Component):
         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 @@ class Timezone(Component):
 
 
 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',)