Document vRecur property

CHANGES.rst

@@ -7,6 +7,7 @@ Changelog
 Minor changes:
 
 - Add a ``weekday`` attribute to ``vWeekday`` components. See `Issue 749 <https://github.com/collective/icalendar/issues/749>`_.
+- Document ``vRecur`` property. See `Issue 758 <https://github.com/collective/icalendar/issues/758>`_.
 - Print failure of doctest to aid debugging.
 
 Breaking changes:
@@ -37,7 +38,7 @@ Minor changes:
 - Merge "File Structure" and "Overview" sections in the docs. See `Issue 626 <https://github.com/collective/icalendar/issues/626>`_.
 - Update code blocks in ``usage.rst`` with the correct lexer.
 - Tidy up the docstring for ``icalendar.prop.vPeriod``.
-- Improve typing and fix typing issues 
+- Improve typing and fix typing issues
 
 
 New features:

docs/usage.rst

@@ -387,7 +387,9 @@ By extending the event with subcomponents, you can create multiple alarms.
     >>> alarm_24h_before.add('description', 'Reminder: Event in 24 hours')
     >>> event.add_component(alarm_24h_before)
 
-Or even recurrence.
+Or even recurrence, either from a dictionary or a string.
+Note that if you want to add the reccurence rule from a string, you must use the ``vRecur`` property.
+Otherwise the rule will be escaped, making it invalid.
 
 .. code-block:: pycon
 

src/icalendar/prop.py

@@ -203,15 +203,15 @@ class vCalAddress(str):
     .. code-block:: text
 
         mailto:[email protected]
-        
+
     .. code-block:: pycon
 
         >>> from icalendar.prop import vCalAddress
         >>> cal_address = vCalAddress.from_ical('mailto:[email protected]')
         >>> cal_address
         vCalAddress('mailto:[email protected]')
 
-      
+
     """
 
     def __new__(cls, value, encoding=DEFAULT_ENCODING):
@@ -259,7 +259,7 @@ class vFloat(float):
             1000000.0000001
             1.333
             -3.14
-        
+
         .. code-block:: pycon
 
             >>> from icalendar.prop import vFloat
@@ -505,11 +505,11 @@ class vDate(TimeBase):
 
     Value Name:
         DATE
-    
+
     Purpose:
         This value type is used to identify values that contain a
         calendar date.
-      
+
     Format Definition:
         This value type is defined by the following notation:
 
@@ -531,7 +531,7 @@ class vDate(TimeBase):
         format specifies a four-digit year, two-digit month, and two-digit
         day of the month.  There are no separator characters between the
         year, month, and day component text.
-    
+
     Example:
         The following represents July 14, 1997:
 
@@ -696,7 +696,7 @@ class vDuration(TimeBase):
         components MUST be added first, that is, the number of days MUST
         be added first, followed by the number of hours, number of
         minutes, and number of seconds.
-      
+
     Example:
         A duration of 15 days, 5 hours, and 20 seconds would be:
 
@@ -709,7 +709,7 @@ class vDuration(TimeBase):
         .. code-block:: text
 
             P7W
-        
+
         .. code-block:: pycon
 
             >>> from icalendar.prop import vDuration
@@ -805,7 +805,7 @@ class vPeriod(TimeBase):
            ; [ISO.8601.2004] complete representation basic format for a
            ; period of time consisting of a start and positive duration
            ; of time.
-       
+
     Description:
         If the property permits, multiple "period" values are
         specified by a COMMA-separated list of values.  There are two
@@ -835,7 +835,7 @@ class vPeriod(TimeBase):
         .. code-block:: text
 
             19970101T180000Z/PT5H30M
-       
+
         .. code-block:: pycon
 
             >>> from icalendar.prop import vPeriod
@@ -1100,6 +1100,73 @@ def __reduce_ex__(self, _p):
 
 class vRecur(CaselessDict):
     """Recurrence definition.
+
+    Property Name:
+        RRULE
+
+    Purpose:
+        This property defines a rule or repeating pattern for recurring events, to-dos,
+        journal entries, or time zone definitions.
+
+    Value Type:
+        RECUR
+
+    Property Parameters:
+        IANA and non-standard property parameters can be specified on this property.
+
+    Conformance:
+        This property can be specified in recurring "VEVENT", "VTODO", and "VJOURNAL"
+        calendar components as well as in the "STANDARD" and "DAYLIGHT" sub-components
+        of the "VTIMEZONE" calendar component, but it SHOULD NOT be specified more than once.
+        The recurrence set generated with multiple "RRULE" properties is undefined.
+
+    Description:
+        The recurrence rule, if specified, is used in computing the recurrence set.
+        The recurrence set is the complete set of recurrence instances for a calendar component.
+        The recurrence set is generated by considering the initial "DTSTART" property along
+        with the "RRULE", "RDATE", and "EXDATE" properties contained within the
+        recurring component. The "DTSTART" property defines the first instance in the
+        recurrence set. The "DTSTART" property value SHOULD be synchronized with the
+        recurrence rule, if specified. The recurrence set generated with a "DTSTART" property
+        value not synchronized with the recurrence rule is undefined.
+        The final recurrence set is generated by gathering all of the start DATE-TIME
+        values generated by any of the specified "RRULE" and "RDATE" properties, and then
+        excluding any start DATE-TIME values specified by "EXDATE" properties.
+        This implies that start DATE- TIME values specified by "EXDATE" properties take
+        precedence over those specified by inclusion properties (i.e., "RDATE" and "RRULE").
+        Where duplicate instances are generated by the "RRULE" and "RDATE" properties,
+        only one recurrence is considered. Duplicate instances are ignored.
+
+        The "DTSTART" property specified within the iCalendar object defines the first
+        instance of the recurrence. In most cases, a "DTSTART" property of DATE-TIME value
+        type used with a recurrence rule, should be specified as a date with local time
+        and time zone reference to make sure all the recurrence instances start at the
+        same local time regardless of time zone changes.
+
+        If the duration of the recurring component is specified with the "DTEND" or
+        "DUE" property, then the same exact duration will apply to all the members of the
+        generated recurrence set. Else, if the duration of the recurring component is
+        specified with the "DURATION" property, then the same nominal duration will apply
+        to all the members of the generated recurrence set and the exact duration of each
+        recurrence instance will depend on its specific start time. For example, recurrence
+        instances of a nominal duration of one day will have an exact duration of more or less
+        than 24 hours on a day where a time zone shift occurs. The duration of a specific
+        recurrence may be modified in an exception component or simply by using an
+        "RDATE" property of PERIOD value type.
+
+    Example:
+        The following RRULE specifies daily events for 10 occurrences.
+
+    .. code-block:: text
+
+        RRULE:FREQ=DAILY;COUNT=10
+
+    .. code-block:: pycon
+
+        >>> from icalendar.prop import vRecur
+        >>> rrule = vRecur.from_ical('FREQ=DAILY;COUNT=10')
+        >>> rrule
+        vRecur({'FREQ': ['DAILY'], 'COUNT': [10]})
     """
 
     frequencies = ["SECONDLY", "MINUTELY", "HOURLY", "DAILY", "WEEKLY",