Add docs in __new__ methods to resolve issue #1118

[Shubham-Developer02]

Closes issue
Closes #1118

Description
This pull request adds Google-style docstrings to the new methods of immutable value types in icalendar.prop so the API docs explain how instances are constructed and how params is attached:

vBoolean (icalendar.prop.boolean)
vFloat (icalendar.prop.float)
vText (icalendar.prop.text)
vCalAddress (icalendar.prop.cal_address)
vUri (icalendar.prop.uri)

• Each docstring summarizes why new is overridden (subclass of int, float, or str), documents Parameters and Returns per the Python docstrings section of the documentation style guide, and includes runnable Examples using .. code-block:: pycon where appropriate.

• No behavioral changes to serialization or parsing are intended; this is documentation only.

Link: icalendar documentation style guide — Python docstrings.

Closes issue

[read-the-docs-community]

Documentation build overview

📚 icalendar | 🛠️ Build #32283392 | 📁 Comparing 066e845 against latest (f0ba179)

  🔍 Preview build  

16 files changed · ± 16 modified

± Modified

• 404.html
• genindex.html
• reference/changelog.html
• reference/api/icalendar.prop.boolean.html
• reference/api/icalendar.prop.cal_address.html
• reference/api/icalendar.prop.float.html
• reference/api/icalendar.prop.text.html
• reference/api/icalendar.prop.uid.html
• reference/api/icalendar.prop.unknown.html
• reference/api/icalendar.prop.uri.html
• and 6 more...

[niccokunzmann]

@Shubham-Developer02 Could you please add a changelog entry?

[niccokunzmann]

Thanks @Shubham-Developer02! I will leave the review to @stevepiercy.

[Shubham-Developer02]

@Shubham-Developer02 Could you please add a changelog entry?
@niccokunzmann , I've added this.

[stevepiercy]

I didn't know that __new__ behaves similarly to __init__ in regards to rendering docstrings. The important admonition at https://icalendar.readthedocs.io/en/latest/contribute/documentation/style-guide.html#docstring-structure describes how to merge a class's and its __init__'s docstrings, but should include __new__ as well.

Additionally, we need to remove duplication of the RFC in our docstrings, and instead document what the class actually does and how to use it, making the docstring more Pythonic. See related issue #1244 for guidance and the discussion.

With all that in mind, @Shubham-Developer02 would you please merge the docstrings of just one class and its __new__ method? Perhaps start with this one, and see how it goes.

https://icalendar--1318.org.readthedocs.build/en/1318/reference/api/icalendar.prop.boolean.html#module-icalendar.prop.boolean

It can be tricky, so I'd suggest building the docs locally. Thank you!

[niccokunzmann]

Hi, we created a new release, please move your edits in CHANGES.rst to the new section.