[zexi25]

Linked issue

• Contributes to apply Google Style to a function documentation [beginner, Python] #1072

Description

Update docstring of _make_unique_tzname(), to_tz(), from_tzid()in src/icalendar/cal/timezone.py to include:

• a one-line summary
• extended description
• Parameters section
• Returns sections

I used AI (Claude Opus 5.5) to review my draft and suggest wording and examples. I verified the final docstring and examples against the implementation.

Checklist

• I added a change log entry, following the instructions in all subsections under Change log requirements.
• I followed icalendar's Artificial intelligence policy and disclosed my Responsible AI use in my commit messages, if applicable.
• I added or updated tests, if applicable.
• I ran and ensured all tests pass locally by following Run tests.
• I added or edited documentation as necessary, both as docstrings to be rendered in the API documentation and narrative documentation, following the Style guide.

Additional information

Documentation preview:
https://icalendar--1878.org.readthedocs.build/en/1878/_modules/icalendar/cal/timezone.html

[github-actions]

Profile summary:

GitHub user: zexi25
🟡 Some 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 zexi25`.

Full profile

GitHub user: zexi25
🟡 Some concerns found with user's profile.
   🟢 Account age: 9 months
   🟡 Profile information:
        name: Zexi
      Empty fields: company, blog, location, email, bio

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

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

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

[github-actions]

This pull request did not pass quality checks and AI use is suspected. Please review Contribute and make any necessary amendments.

[read-the-docs-community]

Documentation build overview

📚 icalendar | 🛠️ Build #34988071 | 📁 Comparing adceb43 against latest (1a12179)

  🔍 Preview build  

1 file changed

± _modules/icalendar/cal/timezone.html

[coveralls-official]

coverage: 97.822%. remained the same — zexi25:patch-1 into collective:main

[niccokunzmann]

Thanks for the PR! There is one suggestion.

In the docstrings, I would like to say what people can expect but not how it is done.

[faresrafat3]

Reviewed this locally on the PR branch.

The change. Docs + type hints: converts _make_unique_tzname docstring to Google style, adds type hints (str, set[str], -> str), and adds a doctest. No runtime behavior change.

Verification. Doctest passes. No issues.

Nothing to fix. Mergeable once CI is green.

[niccokunzmann]

I think, the changelog is correct as we cannot link this.

The documentation also looks alright.

[niccokunzmann]

@zexi25 For this to merge, you will need to rename the changelog file and add a number after it... Someone else also added to this issue.

[zexi25]

@niccokunzmann Appreciate your feedback! I've renamed the changelog with a number suffix. Sorry for accidentally dismissing your review.

[stevepiercy]

This is a nice improvement. Thank you! I made a suggestion to use reStructuredText cross-references that will link to the objects you updated where they're present, and added a few more suggestions that were in the original code that needed to be cleaned up. Would you please take care? Thank you!