docs: clarify optional properties in Alarm.new() docstring

[Aman-0402]

Linked issue

Closes #1473

Description

This PR adds "Optional." to each parameter description in the
Alarm.new() docstring to clarify that these parameters are optional.

Checklist

• I've added a change log entry to /news, following the instructions in Change log entry format.
• I've added or updated tests if applicable. (N/A — docs-only change)
• I've run and ensured all tests pass locally by following Run tests.
• I've added or edited documentation, both as docstrings to be rendered in the API documentation and narrative documentation, as necessary.

Additional information

Docs-only change — no functional code modified.

[github-actions]

Profile summary:

GitHub user: Aman-0402
🟢 No concerns found with user's profile.
🟢 No concerns found with recent PR activity.
🟢 No concerns found with recent issue activity.

For a more detailed report, run `gh-profiler Aman-0402`.

Full profile

GitHub user: Aman-0402
🟢 No concerns found with user's profile.
   🟢 Account age: 3 years
   🟢 Profile information:
        name: Aman Raj
        blog: https://www.linkedin.com/in/aman-raj-081905211/
        location: Bokaro Steel City
        bio:
          Think. Build. Break. Fix. Repeat. Fueled by coffee and questionable ideas.
          Currently coding my way through life, one commit at a time.
        instagram: https://www.instagram.com/epicure_wiz
      Empty fields: company, email

🟢 No concerns found with recent PR activity.
   12 PRs opened in the last 21 days.
      10 opened against repos the user owns.
      0 opened against repos in publicly associated orgs.
      2 opened against external repos.

   🟢 1 of 2 external PRs merged in the last 21 days.
   🟢 0 of 2 external PRs closed without merging in the last 21 days.

🟢 No concerns found with recent issue activity.
   3 new issues opened in the last 21 days.
      3 opened in repos the user owns.
      0 opened in repos in publicly associated orgs.
      0 opened in external repos.

   🟢 0 external issues closed as NOT_PLANNED.
   🟢 0 external issues opened with the same title.

[read-the-docs-community]

Documentation build overview

📚 icalendar | 🛠️ Build #33249274 | 📁 Comparing cc75f33 against latest (a760432)

  🔍 Preview build  

3 files changed

± 404.html
± reference/api/icalendar.cal.alarm.html
± _modules/icalendar/cal/alarm.html

[SashankBhamidi]

Thanks for picking up issue #1473 and taking a stab at the docstring.

Two things need addressing before this can merge:

First, there is no news fragment in news/. The contributing guidelines require one for documentation changes, and the checklist in your PR description has it unchecked. A news/1492.documentation file with a one-line summary and your GitHub handle would do it.

Second, and more importantly: issue #1473 specifically asked for a comparison against RFC 5545 §3.6.6 to understand which properties are actually required versus optional. This PR adds "Optional." uniformly to all eight parameters, but DESCRIPTION is REQUIRED (not optional) for DISPLAY and EMAIL alarm action types per the RFC. The function doesn't have an action parameter, so at this level "optional in Python" is technically accurate since you can construct an Alarm() without one, but I'd like to understand whether you checked the RFC and made a conscious call here, or whether the "Optional." label was added without that context. If the former, adding a note like "Required for DISPLAY and EMAIL action types per :rfc:`5545` §3.6.6" on the description line would give readers the RFC context the issue was asking for.

Procedural note: if any part of this was AI-assisted, please follow the Responsible AI use policy. Standard reminder.

[SashankBhamidi]

DESCRIPTION is listed as unconditionally optional, but RFC 5545 §3.6.6 says it is REQUIRED for DISPLAY and EMAIL action types. Since Alarm.new() doesn't take an action parameter, callers have no way to know this constraint from the docstring alone. Did you check the RFC when writing this? If so, it would be worth adding a note to the description line so users building a DISPLAY or EMAIL alarm know they need to set it. Something like the following would cover it without making the param doc overly long.

Suggested change

	description: Optional. The :attr:`description` of the alarm.
	description: The :attr:`description` of the alarm. Required for DISPLAY and EMAIL action types per :rfc:`5545#section-3.6.6`.

[SashankBhamidi]

@stevepiercy Is it possible to tag the section in the rfc?

[stevepiercy]

@SashankBhamidi thanks for the review. Under General cross-references, there are examples of how to link to a section of an RFC.

Docstring structure also describes how to write docstrings.

[SashankBhamidi]

@SashankBhamidi thanks for the review. Under General cross-references, there are examples of how to link to a section of an RFC.

@stevepiercy I've edited the suggestion, does that look good?

[stevepiercy]

Yes, unless ruff complains about line length.