Repository navigation
docs: clarify new() docstrings of Alarm, Availability, Available and Todo - #1805
sandeep780049 wants to merge 1 commit into
Conversation
|
This pull request did not pass quality checks and AI use is suspected. Please review Contribute and make any necessary amendments. |
|
Profile summary: Full profile |
Documentation build overview
120 files changed ·
|
|
Hi! I've read the AI policy in the contribution guide and want to make sure this PR is fully compliant, since it was flagged as suspected AI use. To be transparent: I used AI assistance to draft this change. It is docs-only — clarifying the From the policy, I understand AI-assisted PRs should have:
I take full responsibility for this change: I reviewed every docstring edit for accuracy against the actual behavior, and CI is green on this PR. Could a maintainer confirm what's needed to proceed? I'm happy to open the backing issue, push an amended commit with the model/usage disclosure in the message, and add the changelog disclosure — whatever is most useful. |
|
Friendly ping for review when you have a moment — small docs-only change clarifying the |
|
Rebased this onto current master so the branch is clean again; the docs-only changes are unchanged. Docs readers can stop when they see the previously seen lines. |
niccokunzmann
left a comment
There was a problem hiding this comment.
Thank you for the PR! The docs changes are fine with me. Could you adjust the changelog?
| @@ -0,0 +1 @@ | |||
| Clarified the ``new()`` docstrings of the calendar components: Availability.new no longer calls itself an event, previously undocumented parameters are now listed, Available.new documents its required start, and Alarm.new points to the action-specific constructors. Verified the docstring grammar against RFC 5545 and RFC 7953. AI-assisted: Claude was used to audit the docstrings against the RFCs and draft the wording. The final change was manually verified. @sandeep780049 | |||
There was a problem hiding this comment.
This is rst and copied into the changelog - can you have a look and make it consistent with the other entries by using links to the methods and classes?
There was a problem hiding this comment.
There was a problem hiding this comment.
Reduce verbosity and link to the methods, per the linked guidance.
| Clarified the ``new()`` docstrings of the calendar components: Availability.new no longer calls itself an event, previously undocumented parameters are now listed, Available.new documents its required start, and Alarm.new points to the action-specific constructors. Verified the docstring grammar against RFC 5545 and RFC 7953. AI-assisted: Claude was used to audit the docstrings against the RFCs and draft the wording. The final change was manually verified. @sandeep780049 | |
| Clarified the docstrings of the calendar components :meth:`Availability.new <icalendar.cal.availability.Availability.new>`, :meth:`Available.new <icalendar.cal.available.Available.new>`, and :meth:`Alarm.new <icalendar.cal.alarm.Alarm.new>`. AI-assisted: Claude was used to audit the docstrings against the RFCs and draft the wording. The final change was manually verified. @sandeep780049 |
| This creates a new Alarm in accordance with :rfc:`5545`. | ||
| Note that :attr:`ACTION` and :attr:`TRIGGER` are required in a | ||
| conforming VALARM, but are not set by this method. | ||
| Use :meth:`new_display`, :meth:`new_audio` or :meth:`new_email` | ||
| to create a valid alarm. |
There was a problem hiding this comment.
I think this method is not in accordance with the RFC. As I interpret the RFC, an alarm must have at least one of (audioprop / dispprop / emailprop) per https://datatracker.ietf.org/doc/html/rfc5545.html#section-3.6.6. It doesn't make sense to have an alarm without at least one kind of notification.
@niccokunzmann how do you want to handle this from a design perspective? Each of the properties has different requirements, and none are validated in accordance the RFC. Is there an issue or pull request that describes what is needed for conformance?
| This creates a new Alarm in accordance with :rfc:`5545`. | |
| Note that :attr:`ACTION` and :attr:`TRIGGER` are required in a | |
| conforming VALARM, but are not set by this method. | |
| Use :meth:`new_display`, :meth:`new_audio` or :meth:`new_email` | |
| to create a valid alarm. | |
| This new Alarm partially conforms with :rfc:`5545#section-3.6.6`. | |
| It requires both an ACTION and TRIGGER property. It doesn't require | |
| a DESCRIPTION property when the ACTION is either DISPLAY or EMAIL. | |
| It doesn't require a SUMMARY property when the ACTION is EMAIL. | |
| Use :meth:`new_display`, :meth:`new_audio` or | |
| :meth:`new_email` to create a valid Alarm. |
| uid: str | uuid.UUID | None = None, | ||
| ) -> Self: | ||
| """Create a new alarm with all required properties. | ||
| """Create a new alarm with the given properties. |
There was a problem hiding this comment.
| """Create a new alarm with the given properties. | |
| """Create a new Alarm with the given properties. |
There was a problem hiding this comment.
This needs to be addressed.
| start: Required. The :attr:`start` of the Available component. | ||
| If ``None``, an :class:`~icalendar.error.InvalidCalendar` is raised. |
There was a problem hiding this comment.
There's an inconsistency between the type hint for start, its implementation, and its docstring. The implementation requires a datetime with a timezone, but the class accepts None for start. I think we should we remove None = None from start's' type hint and adjust this docstring accordingly. What do you think?
@niccokunzmann do you have an opinion here?
There was a problem hiding this comment.
@niccokunzmann still need your opinion for this one, too.
|
@sandeep780049 it's been two weeks since @niccokunzmann requested that you update your PR. We'll close abandoned PRs. |
|
@sandeep780049 would you like to complete work on this PR? Do you need anything from us? Please let us know. Thank you! |
…Todo Fixes parts of PyCalendar#1473: Availability.new no longer describes itself as an event, previously undocumented parameters are now documented, Available.new documents its required start, and Alarm.new points to the action-specific constructors. Adds a news fragment. Responsible AI use: Claude was used to audit the docstrings against RFC 5545 and RFC 7953 and draft the wording. The final change was manually verified.
59a9f02 to
f8e7f2a
Compare
|
Thanks @stevepiercy and @niccokunzmann — pushed an update addressing the review:
Happy to adjust anything else. |
stevepiercy
left a comment
There was a problem hiding this comment.
@sandeep780049 would you please address the missed item?
@niccokunzmann we need your feedback on a couple of items in this PR. Thank you!
Linked issue
newclass methods #1473Description
Audited the constructor docstrings of the unchecked components against the implementation and the applicable RFCs, and corrected the inaccuracies found: a wrong component type in one, three missing parameters, one required argument now documented as required, and one overstated claim removed. One file verified accurate and unchanged. Change log fragment included; Responsible AI use disclosed in the commit message.
Checklist