Add docs in __new__ methods to resolve issue #1118

CHANGES.rst

@@ -48,6 +48,7 @@ Bug fixes
 Documentation
 ~~~~~~~~~~~~~
 
+- Document ``__new__`` for :class:`~icalendar.prop.boolean.vBoolean`, :class:`~icalendar.prop.float.vFloat`, :class:`~icalendar.prop.text.vText`, :class:`~icalendar.prop.cal_address.vCalAddress`, and :class:`~icalendar.prop.uri.vUri` in related docstring examples. :issue: `1118`
 - Run ``sphinx-build`` with ``-W`` to turn warnings into errors. :issue:`1306`
 - Added `sphinx-llms-txt <https://sphinx-llms-txt.readthedocs.io/en/stable/>`_ extension to generate :file:`llms.txt` and :file:`llms-full.txt` files for AI/LLM documentation consumption. :issue:`1302`
 - Fixed CI Vale check reporting and resolved Vale errors. :issue:`1277`

src/icalendar/prop/boolean.py

@@ -55,6 +55,33 @@ class vBoolean(int):
     def __new__(
         cls, *args: Any, params: dict[str, Any] | None = None, **kwargs: Any
     ) -> Self:
+        """Create a new :class:`~icalendar.prop.boolean.vBoolean` instance.
+
+        This method overrides :py:meth:`int.__new__` because BOOLEAN values
+        inherit from :class:`int`, which is immutable. The ``__new__`` method
+        creates the instance and attaches iCalendar property parameters.
+
+        Parameters:
+            *args: Positional arguments passed to :py:meth:`int.__new__`.
+                Typically a single Python :class:`bool` or ``0`` / ``1``.
+            params: Optional property parameters according to :rfc:`5545`.
+            **kwargs: Additional keyword arguments passed to
+                :py:meth:`int.__new__`.
+
+        Returns:
+            A new :class:`~icalendar.prop.boolean.vBoolean` instance with
+            associated parameters.
+
+        Examples:
+            .. code-block:: pycon
+
+                >>> from icalendar import vBoolean
+                >>> b = vBoolean(True, params={"VALUE": "BOOLEAN"})
+                >>> bool(b)
+                True
+                >>> b.params
+                Parameters({'VALUE': 'BOOLEAN'})
+        """
         self = super().__new__(cls, *args, **kwargs)
         self.params = Parameters(params)
         return self

src/icalendar/prop/cal_address.py

@@ -66,6 +66,37 @@ def __new__(
         /,
         params: dict[str, Any] | None = None,
     ) -> Self:
+        """Create a new :class:`~icalendar.prop.cal_address.vCalAddress` instance.
+
+        This method overrides :py:meth:`str.__new__` because CAL-ADDRESS values
+        inherit from :class:`str`, which is immutable. The ``__new__`` method
+        decodes bytes if needed, creates the string instance, and attaches
+        iCalendar property parameters.
+
+        Parameters:
+            value: Calendar user address, usually a ``mailto`` URI as defined in
+                :rfc:`5545#section-3.3.3`, passed through
+                :func:`~icalendar.parser_tools.to_unicode`.
+            encoding: Encoding used when ``value`` is :class:`bytes`.
+            params: Optional property parameters according to :rfc:`5545`.
+
+        Returns:
+            A new :class:`~icalendar.prop.cal_address.vCalAddress` instance with
+            associated parameters.
+
+        Examples:
+            .. code-block:: pycon
+
+                >>> from icalendar import vCalAddress
+                >>> a = vCalAddress(
+                ...     "mailto:jsmith@example.com",
+                ...     params={"CN": "John Smith"},
+                ... )
+                >>> str(a)
+                'mailto:jsmith@example.com'
+                >>> a.params["CN"]
+                'John Smith'
+        """
         value = to_unicode(value, encoding=encoding)
         self = super().__new__(cls, value)
         self.params = Parameters(params)

src/icalendar/prop/float.py

@@ -59,6 +59,34 @@ class vFloat(float):
     def __new__(
         cls, *args: Any, params: dict[str, Any] | None = None, **kwargs: Any
     ) -> Self:
+        """Create a new :class:`~icalendar.prop.float.vFloat` instance.
+
+        This method overrides :py:meth:`float.__new__` because FLOAT values
+        inherit from :class:`float`, which is immutable. The ``__new__`` method
+        creates the instance and attaches iCalendar property parameters.
+
+        Parameters:
+            *args: Positional arguments passed to :py:meth:`float.__new__`.
+                Typically a single numeric value or string accepted by
+                :class:`float`.
+            params: Optional property parameters according to :rfc:`5545`.
+            **kwargs: Additional keyword arguments passed to
+                :py:meth:`float.__new__`.
+
+        Returns:
+            A new :class:`~icalendar.prop.float.vFloat` instance with
+            associated parameters.
+
+        Examples:
+            .. code-block:: pycon
+
+                >>> from icalendar import vFloat
+                >>> x = vFloat(1.333, params={"VALUE": "FLOAT"})
+                >>> float(x)
+                1.333
+                >>> x.params
+                Parameters({'VALUE': 'FLOAT'})
+        """
         self = super().__new__(cls, *args, **kwargs)
         self.params = Parameters(params)
         return self

src/icalendar/prop/text.py

@@ -76,6 +76,35 @@ def __new__(
         /,
         params: dict[str, Any] | None = None,
     ) -> Self:
+        """Create a new :class:`~icalendar.prop.text.vText` instance.
+
+        This method overrides :py:meth:`str.__new__` because TEXT values
+        inherit from :class:`str`, which is immutable. The ``__new__`` method
+        decodes bytes if needed, creates the string instance, and attaches
+        encoding metadata and iCalendar property parameters.
+
+        Parameters:
+            value: Raw text passed to :func:`~icalendar.parser_tools.to_unicode`
+                before constructing the :class:`str` value.
+            encoding: Encoding used when ``value`` is :class:`bytes`.
+            params: Optional property parameters according to :rfc:`5545`.
+
+        Returns:
+            A new :class:`~icalendar.prop.text.vText` instance with
+            associated parameters.
+
+        Examples:
+            .. code-block:: pycon
+
+                >>> from icalendar import vText
+                >>> t = vText("Hello", params={"LANGUAGE": "en"})
+                >>> str(t)
+                'Hello'
+                >>> t.encoding
+                'utf-8'
+                >>> t.params
+                Parameters({'LANGUAGE': 'en'})
+        """
         value = to_unicode(value, encoding=encoding)
         self = super().__new__(cls, value)
         self.encoding = encoding

src/icalendar/prop/uri.py

@@ -65,6 +65,36 @@ def __new__(
         /,
         params: dict[str, Any] | None = None,
     ) -> Self:
+        """Create a new :class:`~icalendar.prop.uri.vUri` instance.
+
+        This method overrides :py:meth:`str.__new__` because URI values inherit
+        from :class:`str`, which is immutable. The ``__new__`` method decodes
+        bytes if needed, creates the string instance, and attaches iCalendar
+        property parameters.
+
+        Parameters:
+            value: URI string or bytes decoded with ``encoding``, passed through
+                :func:`~icalendar.parser_tools.to_unicode`.
+            encoding: Encoding used when ``value`` is :class:`bytes`.
+            params: Optional property parameters according to :rfc:`5545`.
+
+        Returns:
+            A new :class:`~icalendar.prop.uri.vUri` instance with associated
+            parameters.
+
+        Examples:
+            .. code-block:: pycon
+
+                >>> from icalendar import vUri
+                >>> u = vUri(
+                ...     "http://example.com/agenda.doc",
+                ...     params={"VALUE": "URI"},
+                ... )
+                >>> u.uri
+                'http://example.com/agenda.doc'
+                >>> u.params["VALUE"]
+                'URI'
+        """
         value = to_unicode(value, encoding=encoding)
         self = super().__new__(cls, value)
         self.params = Parameters(params)