collective / icalendar / 33352456655

98%

push

github

Rewrite COMMENT and CONTACT docstrings to be Pythonic (issue #1244) (#1727)

* Rewrite COMMENT and CONTACT docstrings to be Pythonic (issue #1244)

Replace RFC copy-paste (Purpose/Conformance/Property Parameters) in
comments_property and contacts_property with Pythonic docstrings that
summarize behaviour, link the relevant RFC sections with :rfc: cross
references, and include runnable pycon doctests.

Both properties are shared by Event, Todo, Journal, Calendar and the
availability components, so this improves many tracked docstring items
at once. Doctests verified with pytest --doctest-modules.

* Add changelog entry for docstring rewrite (issue #1244)

Per maintainer review (stevepiercy): add a towncrier news entry so the
change can be credited and merged. Documents the COMMENT/CONTACT
docstring rewrite in news/1727.documentation.rst.

* Make COMMENT/CONTACT docstrings concise per review

Apply stevepiercy's review: shorten summaries, drop self-referential
'See also' links that don't resolve (no comments/contacts component
methods exist), and remove the copy-pasted RFC ics example from CONTACT.
Doctests + test_docstrings.py (1695 passed) stay green.

* Apply batched suggestions from code review

Co-authored-by: Steve Piercy <web@stevepiercy.com>

---------

Co-authored-by: Steve Piercy <web@stevepiercy.com>

1660 of 1800 branches covered (92.22%)

Branch coverage included in aggregate %.

14601 of 14872 relevant lines covered (98.18%)

6.87 hits per line