docs: convert Component._encode docstring to Google style by harsh8968 · Pull Request #1617 · collective/icalendar

harsh8968 · 2026-07-31T09:56:46Z

Linked issue

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

Description

Converts the Component._encode docstring in src/icalendar/cal/component.py from the old Sphinx :param:/:type:/:returns: markup to the project's Google-style Parameters/Returns format, per the style guide. Docstring only, no behavior change.

Checklist

I added a change log entry, following the instructions in Change log entry format.
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

Verified with ruff check/ruff format --check, the test_docstring_of_python_file[icalendar.cal.component] doctest, and the full component/encode-related test selection — all pass. The unrelated test_timezone_identification.py/test_issue_722_generate_vtimezone.py failures in the full suite are a pre-existing dateutil/tzdata environment issue on Windows, reproducible on a clean main checkout without this change.

I'm a first-time contributor and used Claude (Anthropic) to help find an unclaimed part of #1072 and draft the docstring per the style guide; disclosed per the AI policy.

Contributes to collective#1072. Replaces the Sphinx-style :param:/:type:/:returns: markup on Component._encode with the project's Google-style Parameters/Returns sections, per the documentation style guide. No behavior change. AI disclosure: I used Claude (Anthropic, Sonnet 5) to identify an unclaimed target for icalendar issue collective#1072, draft the converted docstring text following the project's style guide, and verify it locally (ruff, pytest, doctest). I reviewed and validated the change.

github-actions · 2026-07-31T09:56:55Z

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

github-actions · 2026-07-31T09:57:01Z

Profile summary:

GitHub user: harsh8968
🔴 Significant 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 harsh8968`.

Full profile

GitHub user: harsh8968
🔴 Significant concerns found with user's profile.
   🟢 Account age: 4 years
   🔴 No profile information provided.

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

   🟢 0 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.
   🟢 No new issues opened in the last 21 days.

read-the-docs-community · 2026-07-31T09:57:48Z

Documentation build overview

📚 icalendar | 🛠️ Build #33850198 | 📁 Comparing d5ae6dd against latest (926bc02)

🔍 Preview build

2 files changed

± 404.html
± _modules/icalendar/cal/component.html

stevepiercy

This is a good start. I realized I omitted a critical piece, specifically that the type of the parameter must be specified, either in the signature's type hints or in the parameter's docstring, with type hints preferred. I also suggested to change the booleans to inline literals. Would you please take care? Thank you!

stevepiercy · 2026-07-31T11:20:24Z

-        :type encode: Boolean
+        Parameters:
+            name: Name of the property.
+            value: Value of the property. Either a basic Python type or


Suggested change

value: Value of the property. Either a basic Python type or

value: Value of the property. Either a native Python type or

stevepiercy · 2026-07-31T11:22:23Z

@@ -248,23 +248,18 @@ def is_empty(self) -> bool:
    def _encode(cls, name, value, parameters=None, encode=1):


When converting to Google style, you must either add type hints in the signature or name the parameter's type. Type hints are preferred. Sorry that wasn't clear in the requirements.

It would be good to include that in both the documentation and original issue. I'll handle both of these.

The signature has no type hints and the docstring does not name the types for any parameter. The style guide (updated since this PR opened) requires one or the other.

Since _encode is a private method and encode defaults to 1 rather than True, adding type hints to the signature risks a misleading annotation.

Adding inline types in the docstring is safer here; see the style guide's type hints section for the format.

stevepiercy · 2026-07-31T11:25:16Z

+            value: Value of the property. Either a basic Python type or
+                any of icalendar's own property types.
+            parameters: Property parameter dictionary for the value. Only
+                used if encode is set to True.


The original should have used inline literals.

Suggested change

used if encode is set to True.

used if encode is set to ``True``.

stevepiercy · 2026-07-31T11:25:44Z

+            encode: True if the value should be encoded to one of
+                icalendar's own property types (falls back to ``vText``),
+                or False if not.


Suggested change

encode: True if the value should be encoded to one of

icalendar's own property types (falls back to ``vText``),

or False if not.

encode: ``True`` if the value should be encoded to one of

icalendar's own property types (falls back to ``vText``),

or ``False`` if not.

stevepiercy · 2026-07-31T11:28:16Z

@@ -0,0 +1 @@
+Converted the ``Component._encode`` docstring from Sphinx ``:param:``/``:type:``/``:returns:`` markup to the project's Google-style ``Parameters``/``Returns`` format. I used AI (Claude) to help draft the docstring and this entry. @harsh8968


Use the full path for methods that don't render in the documentation. Also the minutia of how it was changed are unnecessary.

Suggested change

Converted the ``Component._encode`` docstring from Sphinx ``:param:``/``:type:``/``:returns:`` markup to the project's Google-style ``Parameters``/``Returns`` format. I used AI (Claude) to help draft the docstring and this entry. @harsh8968

Converted the ``icalendar.cal.component.Component._encode`` docstring from the default Sphinx markup to the project's Google-style format. I used AI (Claude) to help draft the docstring and this entry. @harsh8968

SashankBhamidi

Thanks for the conversion.

Steve's suggestions are all still open, please apply them before this merges.

@stevepiercy Do you want to batch add them and merge? Since there's not response from the author for over a week.

SashankBhamidi · 2026-08-06T08:00:24Z

@@ -248,23 +248,18 @@ def is_empty(self) -> bool:
    def _encode(cls, name, value, parameters=None, encode=1):


The signature has no type hints and the docstring does not name the types for any parameter. The style guide (updated since this PR opened) requires one or the other.

Since _encode is a private method and encode defaults to 1 rather than True, adding type hints to the signature risks a misleading annotation.

Adding inline types in the docstring is safer here; see the style guide's type hints section for the format.

stevepiercy · 2026-08-06T11:16:25Z

@stevepiercy Do you want to batch add them and merge? Since there's not response from the author for over a week.

This PR was created 6 days ago. Especially during summer and winter when people go on extended vacations, I'm inclined to let contributors have time away for life, and allow at least two weeks for them to respond to feedback.

After that period elapses, I'd post another comment asking them if they need anything from us to address the feedback, then wait at least two more weeks before taking it over. That's a general rule, but exceptions may apply, such as if it's a high priority contribution. Docstring conversions, although important, are a low priority.

harsh8968 requested review from SashankBhamidi, angatha, niccokunzmann and stevepiercy as code owners July 31, 2026 09:56

github-actions Bot added the ai-suspicion This contribution is possibly created with lots of AI help without enough human understanding. label Jul 31, 2026

stevepiercy requested changes Jul 31, 2026

View reviewed changes

This was referenced Jul 31, 2026

Document how to document the order of parameters in docstrings #1618

Closed

Merge __init__ or __new__ docstrings into their class's docstring #1620

Open

SashankBhamidi approved these changes Aug 6, 2026

View reviewed changes

stevepiercy added the doc label Aug 23, 2026

	value: Value of the property. Either a basic Python type or
	value: Value of the property. Either a native Python type or

		@@ -248,23 +248,18 @@ def is_empty(self) -> bool:
		def _encode(cls, name, value, parameters=None, encode=1):

	used if encode is set to True.
	used if encode is set to ``True``.

		@@ -0,0 +1 @@
		Converted the ``Component._encode`` docstring from Sphinx ``:param:``/``:type:``/``:returns:`` markup to the project's Google-style ``Parameters``/``Returns`` format. I used AI (Claude) to help draft the docstring and this entry. @harsh8968

	Converted the ``Component._encode`` docstring from Sphinx ``:param:``/``:type:``/``:returns:`` markup to the project's Google-style ``Parameters``/``Returns`` format. I used AI (Claude) to help draft the docstring and this entry. @harsh8968
	Converted the ``icalendar.cal.component.Component._encode`` docstring from the default Sphinx markup to the project's Google-style format. I used AI (Claude) to help draft the docstring and this entry. @harsh8968

Uh oh!

Uh oh!

Conversation

harsh8968 commented Jul 31, 2026

Linked issue

Description

Checklist

Additional information

Uh oh!

github-actions Bot commented Jul 31, 2026

Uh oh!

github-actions Bot commented Jul 31, 2026

Uh oh!

read-the-docs-community Bot commented Jul 31, 2026

Documentation build overview

Uh oh!

stevepiercy left a comment

Choose a reason for hiding this comment

Uh oh!

stevepiercy Jul 31, 2026

Choose a reason for hiding this comment

Uh oh!

stevepiercy Jul 31, 2026

Choose a reason for hiding this comment

Uh oh!

SashankBhamidi Aug 6, 2026

Choose a reason for hiding this comment

Uh oh!

stevepiercy Jul 31, 2026

Choose a reason for hiding this comment

Uh oh!

stevepiercy Jul 31, 2026

Choose a reason for hiding this comment

Uh oh!

stevepiercy Jul 31, 2026

Choose a reason for hiding this comment

Uh oh!

SashankBhamidi left a comment

Choose a reason for hiding this comment

Uh oh!

SashankBhamidi Aug 6, 2026

Choose a reason for hiding this comment

Uh oh!

stevepiercy commented Aug 6, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants