Document Properties with Text from RFC 5545

[niccokunzmann]

The RFC 5545 describes all the properties we have in icalendar.prop.

Please add a __doc__ string documentation for all of them.

Examples:

• vMonth

class vGeo:
    """Geographic Position

    Property Name:  GEO

    Purpose:  This property specifies information related to the global
        position for the activity specified by a calendar component.

    Value Type:  FLOAT.  The value MUST be two SEMICOLON-separated FLOAT
        values.

    Property Parameters:  IANA and non-standard property parameters can
        be specified on this property.

    Conformance:  This property can be specified in "VEVENT" or "VTODO"
        calendar components.

    Description:  This property value specifies latitude and longitude,
        in that order (i.e., "LAT LON" ordering).  The longitude
        represents the location east or west of the prime meridian as a
        positive or negative real number, respectively.  The longitude and
        latitude values MAY be specified up to six decimal places, which
        will allow for accuracy to within one meter of geographical
        position.  Receiving applications MUST accept values of this
        precision and MAY truncate values of greater precision.

    Example:
        GEO:37.386013;-122.082932

        >>> geo = vGeo.from_ical('37.386013;-122.082932')
        >>> geo.latitude
        37.386013
        >>> geo.longitude
        -122.082932
    """

This includes:

• heading
• description that gives a rough overview
• example from the RFC
• example code for icalendar

Please add one of these in a PR:

• vBinary
• vBoolean
• vCalAddress
• vDate
• vDatetime
• vDuration
• vFloat
• vFrequency
• vGeo
• vInt
• vPeriod
• vRecur
• vText
• vTime
• vUTCOffset
• vUri
• vWeekday
• vSkip

The following ones are special because they consist of different properties. Here, we just need a few examples of how to parse with them in from_ical() and examples of how to create them and make ics strings in to_ical()

• vDDDLists - this is a list of datetime/date values
• vDDDTypes - this is any of the time values - a nice way to just parse if you do not know what you are having as a value

After all these classes are done:

• When all classes are documented, please go through all of them and make sure they are in a consistent, nice format and it renders will on readthedocs. See also: Which docstring format should we use? #747

See also:

• Copy documentation from RFC into the components #726

[SerifOZ]

Can I work this issue?

[niccokunzmann]

Yes, please!

[niccokunzmann]

@stevepiercy If you can have a look at this issue and make the example docstring "perfect" or create a PR for a perfect docstring in e.g. vGeo, that would help the other classes. Then, we can open another issue after this is solved to "unify the format" according to the one example.

[stevepiercy]

@niccokunzmann First, why would we document RFCs again with a copy-paste into our docstrings? Now that I've been paying more attention to the docstrings, I don't understand why that was done in the first place.

I think instead we should refer or link to them, and use their content to document icalendar's Python implementation to comply with the RFCs as needed. We can also use their examples for the input and output of the Python implementation in the docstrings as doctests. Does that make sense?

Please let me know what you think. Thank you!

[niccokunzmann]

I like it copied because that allows modification, checking it for completeness while programming, linking and adjusting to what we need. For vText, there is not much to do - it is only RFC 5545. However, once RFCs get combined into one property, it is not obvious what that means just by linking. It is nice e.g. to see all the examples in the documentation and have some context, see how RFC examples are converted into Python examples and also structure it the way it makes sense for us and the reader - especially if several RFCs influence the behaviour of a property, a VPROPERTY or a component.