Fix FreeBusy.new() docstring referencing alarm instead of free/busy by andycheng2018 · Pull Request #1503 · collective/icalendar

andycheng2018 · 2026-06-24T05:25:57Z

Linked issue

See Clarify auto-generated properties for new class methods #1473

Description

The FreeBusy.new() docstring summary was copied from the Alarm class and
incorrectly described creating an alarm. This corrects it to reference the
free/busy component.

I also verified the property required/optional structure for VFREEBUSY against
RFC 5545 §3.6.4, and the implementation already matches the specification, so
only the docstring summary text needed correcting.

This addresses the src/icalendar/cal/free_busy.py item from the checklist in #1473.

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. (Not applicable: this is a docstring text correction with no behavioral change.)
I've run and ensured all tests pass locally.
I've added or edited documentation (the corrected docstring renders in the API documentation).

Additional information

AI assistance: Claude Opus 4.5 (Anthropic), used via the web chat interface to
help locate the issue, verify the property structure against RFC 5545, and draft
the docstring correction. I reviewed and validated the change and take
responsibility for it. This is also disclosed in the commit message and the
changelog entry.

The FreeBusy.new() docstring summary was copied from the Alarm class and incorrectly described creating an alarm. Corrected it to reference the free/busy component. Verified the property structure against RFC 5545 section 3.6.4; the implementation already matches, only the docstring text was inaccurate. AI assistance: Claude Opus 4.5 (Anthropic), used via the web chat interface to help locate the issue, verify the property structure against RFC 5545, and draft the docstring correction. I reviewed and validated the change and take responsibility for it.

github-actions · 2026-06-24T05:26:08Z

Profile summary:

GitHub user: andycheng2018
🟢 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 andycheng2018`.

Full profile

GitHub user: andycheng2018
🟢 No concerns found with user's profile.
   🟢 Account age: 3 years
   🟢 Profile information:
        name: Andy Cheng
      Empty fields: company, blog, location, email, bio

🟢 No concerns found with recent PR activity.
   🟢 No PRs opened in the last 21 days.

🟢 No concerns found with recent issue activity.
   🟢 No new issues opened in the last 21 days.

read-the-docs-community · 2026-06-24T05:27:07Z

Documentation build overview

📚 icalendar | 🛠️ Build #33760888 | 📁 Comparing 9251120 against latest (937f6fc)

🔍 Preview build

65 files changed · + 2 added · ± 63 modified

+ Added

± Modified

niccokunzmann

Hi, please do not use AI for this. Read through the other classes' doc strings and checkhow we name the components and be consistent with that.

…f alarm Aligns docstring structure with Event.new() convention (summary line + RFC reference line) while linking directly to RFC 5545 section 3.6.4 for precision, per review feedback.

andycheng2018 · 2026-07-19T21:26:30Z

Hi, thanks for the feedback. I've made changes based on the grammar/syntax I saw in event.py. Hope the new changes help!

stevepiercy · 2026-07-20T19:01:02Z

@andycheng2018 please address @niccokunzmann's comment #1503 (review).

stevepiercy

Docstrings and news are OK, but still needs to address the naming convention issue that @niccokunzmann pointed out.

coveralls · 2026-07-20T19:18:34Z

coverage: 97.927% (+0.01%) from 97.916% — andycheng2018:fix-freebusy-docstring into collective:main

Matches how Event.new() refers to "the event" in its parameter docs. Also fixed the Raises: line, it was missing the :exc: role.

andycheng2018 · 2026-07-26T02:00:04Z

Hey, thanks for the feedback! I took another look at event.py and updated the docstring so the parameters say "of the free/busy" instead of "of the component" and other parameters to match the two. Let me know if this looks good.

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

Replaced the RFC-citation sentence with an explicit list of required properties (UID and DTSTAMP), per stevepiercy's suggestion.

stevepiercy

One more minor improvement, and then I approve. Thanks for your patience!

Per stevepiercy's suggestion, note that UID and DTSTAMP may be set via the uid and stamp parameters.

andycheng2018 · 2026-07-26T02:57:39Z

No worries, thanks for walking me through this!

stevepiercy

Thank you!

andycheng2018 requested review from SashankBhamidi, angatha, niccokunzmann and stevepiercy as code owners June 24, 2026 05:25

niccokunzmann assigned stevepiercy Jun 24, 2026

andycheng2018 added 3 commits July 1, 2026 16:21

Merge branch 'main' into fix-freebusy-docstring

561a936

Merge branch 'main' into fix-freebusy-docstring

522292c

Merge branch 'main' into fix-freebusy-docstring

bfe4e30

stevepiercy requested changes Jul 12, 2026

View reviewed changes

Comment thread src/icalendar/cal/free_busy.py Outdated

niccokunzmann requested changes Jul 12, 2026

View reviewed changes

Fix FreeBusy.new() docstring: reference free/busy component instead o…

8bdba44

…f alarm Aligns docstring structure with Event.new() convention (summary line + RFC reference line) while linking directly to RFC 5545 section 3.6.4 for precision, per review feedback.

Merge branch 'main' into fix-freebusy-docstring

46fc2b2

stevepiercy previously approved these changes Jul 20, 2026

View reviewed changes

Use "free/busy" instead of "component" in FreeBusy.new() docstring

0bfc9cd

Matches how Event.new() refers to "the event" in its parameter docs. Also fixed the Raises: line, it was missing the :exc: role.

andycheng2018 dismissed stevepiercy’s stale review via 0bfc9cd July 26, 2026 01:56

Merge branch 'main' into fix-freebusy-docstring

d5b8bfb

stevepiercy requested changes Jul 26, 2026

View reviewed changes

Comment thread src/icalendar/cal/free_busy.py

Comment thread src/icalendar/cal/free_busy.py Outdated

Comment thread src/icalendar/cal/free_busy.py Outdated

Comment thread news/1473.documentation Outdated

andycheng2018 and others added 3 commits July 25, 2026 19:27

Update news/1473.documentation

e2b432d

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

Update src/icalendar/cal/free_busy.py

c633868

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

Name the required properties in FreeBusy.new() docstring

48263c0

Replaced the RFC-citation sentence with an explicit list of required properties (UID and DTSTAMP), per stevepiercy's suggestion.

stevepiercy requested changes Jul 26, 2026

View reviewed changes

Comment thread src/icalendar/cal/free_busy.py Outdated

Connect required properties to their new() parameter names

9251120

Per stevepiercy's suggestion, note that UID and DTSTAMP may be set via the uid and stamp parameters.

stevepiercy approved these changes Jul 26, 2026

View reviewed changes

stevepiercy requested a review from niccokunzmann July 26, 2026 02:59

stevepiercy assigned niccokunzmann Jul 26, 2026

stevepiercy enabled auto-merge (squash) July 26, 2026 03:00

Uh oh!

Uh oh!

Conversation

andycheng2018 commented Jun 24, 2026

Linked issue

Description

Checklist

Additional information

Uh oh!

github-actions Bot commented Jun 24, 2026

Uh oh!

read-the-docs-community Bot commented Jun 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Documentation build overview

Uh oh!

Uh oh!

niccokunzmann left a comment

Choose a reason for hiding this comment

Uh oh!

andycheng2018 commented Jul 19, 2026

Uh oh!

stevepiercy commented Jul 20, 2026

Uh oh!

stevepiercy left a comment

Choose a reason for hiding this comment

Uh oh!

coveralls commented Jul 20, 2026

Uh oh!

andycheng2018 commented Jul 26, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

stevepiercy left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

andycheng2018 commented Jul 26, 2026

Uh oh!

stevepiercy left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

read-the-docs-community Bot commented Jun 24, 2026 •

edited

Loading