diff --git a/CHANGES.rst b/CHANGES.rst index 42f722f9b..c0753235a 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -57,6 +57,7 @@ Bug fixes Documentation ~~~~~~~~~~~~~ +- Convert docstring of :meth:`~icalendar.cal.component.Component.add` to Google style. :issue:`1072` - Convert docstring of :func:`~icalendar.param.string_parameter` to Google style. :issue:`1072`, :pr:`1316` - Run ``sphinx-build`` with ``-W`` to turn warnings into errors. :issue:`1306` - Added `sphinx-llms-txt `_ extension to generate :file:`llms.txt` and :file:`llms-full.txt` files for AI/LLM documentation consumption. :issue:`1302` diff --git a/src/icalendar/cal/component.py b/src/icalendar/cal/component.py index 51f63d9f3..3401d8f56 100644 --- a/src/icalendar/cal/component.py +++ b/src/icalendar/cal/component.py @@ -286,25 +286,35 @@ def add( parameters: dict[str, str] | Parameters = None, encode: bool = True, ): - """Add a property. + """Add a property to this component. - :param name: Name of the property. - :type name: string - - :param value: Value of the property. Either of a basic Python type of - any of the icalendar's own property types. - :type value: Python native type or icalendar property type. + If the property already exists, the new value is appended so the + property carries a list of values rather than replacing the previous + one. When ``name`` is ``DTSTAMP``, ``CREATED``, or ``LAST-MODIFIED`` + and ``value`` is a ``datetime``, the value is converted to UTC as the + RFC requires. - :param parameters: Property parameter dictionary for the value. Only - available, if encode is set to True. - :type parameters: Dictionary + Parameters: + name: Name of the property. + value: + Value of the property. Either a basic Python type or any of + icalendar's own property types. + parameters: + Property parameter dictionary for the value. Only consulted + when ``encode`` is ``True``. + encode: + ``True`` if the value should be encoded to one of icalendar's + own property types (fallback is ``vText``); ``False`` to + store the value as-is. + + Example: - :param encode: True, if the value should be encoded to one of - icalendar's own property types (Fallback is "vText") - or False, if not. - :type encode: Boolean + >>> from icalendar import Event + >>> event = Event() + >>> event.add("summary", "Team sync") + >>> event["summary"] + vText(b'Team sync') - :returns: None """ if isinstance(value, datetime) and name.lower() in ( "dtstamp",