Skip to content

docs: convert Component.add docstring to Google Style#1390

Open
mvanhorn wants to merge 1 commit into
collective:mainfrom
mvanhorn:osc-1072-google-style
Open

docs: convert Component.add docstring to Google Style#1390
mvanhorn wants to merge 1 commit into
collective:mainfrom
mvanhorn:osc-1072-google-style

Conversation

@mvanhorn
Copy link
Copy Markdown
Contributor

@mvanhorn mvanhorn commented May 16, 2026

Summary

Contributes to #1072.

Converts the Component.add docstring in src/icalendar/cal/component.py from reStructuredText :param: / :returns: syntax to Google Style with Parameters:, Returns (omitted, returns nothing), and an Example: block. Follows the pattern set by #1316 (string_parameter) and #1309 (caselessdict).

The Example block adds a runnable doctest that verifies Component.add correctly stores the value as a vText (Team syncvText(b'Team sync')).

Also adds a CHANGES.rst entry under the Documentation section.

Why these changes

The original docstring used :param name: ... :type name: string :returns: None. The project's style guide now expects Google Style headings and inline type information. This PR is one more step toward the consistent format described in #1072.

Verification

  • python3 -m doctest src/icalendar/cal/component.py (run from src/): the new Component.add example block passes. (Three unrelated pre-existing failures in links, to_jcal, and uid are about hardcoded UIDs/timestamps and are not touched by this PR.)
  • No code behavior change — docstring only.

Documentation preview

The Read the Docs preview will be linked by the bot after this PR is opened. The function shows up at icalendar.cal.component.Component.add.


📚 Documentation preview 📚: https://icalendar--1390.org.readthedocs.build/

@read-the-docs-community
Copy link
Copy Markdown

Documentation build overview

📚 icalendar | 🛠️ Build #32715840 | 📁 Comparing 2ccd9bc against latest (c343662)

  🔍 Preview build  

4 files changed
± 404.html
± reference/changelog.html
± reference/api/icalendar.cal.component.html
± _modules/icalendar/cal/component.html

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant