From 7a8ddfc2bd30c3b5db65146f1affb0237010779e Mon Sep 17 00:00:00 2001
From: Viicos <65306057+Viicos@users.noreply.github.com>
Date: Wed, 23 Jul 2025 21:21:33 +0200
Subject: [PATCH] Fix various documentation layout issues

---
 pydantic_extra_types/pendulum_dt.py   |  5 +--
 pydantic_extra_types/phone_numbers.py | 48 ++++++++++++++-------------
 2 files changed, 26 insertions(+), 27 deletions(-)

diff --git a/pydantic_extra_types/pendulum_dt.py b/pydantic_extra_types/pendulum_dt.py
index e0fdbf2..bfbac99 100644
--- a/pydantic_extra_types/pendulum_dt.py
+++ b/pydantic_extra_types/pendulum_dt.py
@@ -200,11 +200,8 @@ def to_iso8601_string(self) -> str:
 
         In addition to the standard ISO 8601 format, this method also supports the representation of fractions of a second and negative durations.
 
-        Args:
-            duration (Duration): The Duration object.
-
         Returns:
-            str: The ISO 8601 string representation of the duration.
+            The ISO 8601 string representation of the duration.
         """
         # Extracting components from the Duration object
         years = self.years
diff --git a/pydantic_extra_types/phone_numbers.py b/pydantic_extra_types/phone_numbers.py
index 880446f..e86f8dd 100644
--- a/pydantic_extra_types/phone_numbers.py
+++ b/pydantic_extra_types/phone_numbers.py
@@ -1,7 +1,8 @@
 """The `pydantic_extra_types.phone_numbers` module provides the
 [`PhoneNumber`][pydantic_extra_types.phone_numbers.PhoneNumber] data type.
 
-This class depends on the [phonenumbers] package, which is a Python port of Google's [libphonenumber].
+This class depends on the [phonenumbers](https://pypi.orgt/phonenumbers/) package,
+which is a Python port of Google's [libphonenumber](https://github.com/google/libphonenumber/).
 """
 
 from __future__ import annotations
@@ -25,15 +26,14 @@
 
 
 class PhoneNumber(str):
-    """A wrapper around [phonenumbers](https://pypi.org/project/phonenumbers/) package, which
-    is a Python port of Google's [libphonenumber](https://github.com/google/libphonenumber/).
-    """
+    """A wrapper around the `phonenumbers.PhoneNumber` object."""
+
+    default_region_code: ClassVar[str | None] = None
+    """The default region code to use when parsing phone numbers without an international prefix."""
 
     supported_regions: list[str] = []
     """The supported regions. If empty, all regions are supported."""
 
-    default_region_code: ClassVar[str | None] = None
-    """The default region code to use when parsing phone numbers without an international prefix."""
     phone_format: str = 'RFC3966'
     """The format of the phone number."""
 
@@ -78,38 +78,40 @@ def __hash__(self) -> int:
 
 @dataclass(frozen=True)
 class PhoneNumberValidator:
-    """A pydantic before validator for phone numbers using the [phonenumbers](https://pypi.org/project/phonenumbers/) package,
-    a Python port of Google's [libphonenumber](https://github.com/google/libphonenumber/).
+    """An annotation to validate `phonenumbers.PhoneNumber` objects.
 
-    Intended to be used to create custom pydantic data types using the `typing.Annotated` type construct.
+    Example:
+        ```python
+        from typing import Annotated, Union
 
-    Args:
-        default_region (str | None): The default region code to use when parsing phone numbers without an international prefix.
-            If `None` (default), the region must be supplied in the phone number as an international prefix.
-        number_format (str): The format of the phone number to return. See `phonenumbers.PhoneNumberFormat` for valid values.
-        supported_regions (list[str]): The supported regions. If empty, all regions are supported (default).
+        import phonenumbers
+        from pydantic import BaseModel
+        from pydantic_extra_types.phone_numbers import PhoneNumberValidator
 
-    Returns:
-        The formatted phone number.
+        MyNumberType = Annotated[Union[str, phonenumbers.PhoneNumber], PhoneNumberValidator()]
 
-    Example:
-        MyNumberType = Annotated[
-            Union[str, phonenumbers.PhoneNumber],
-            PhoneNumberValidator()
-        ]
         USNumberType = Annotated[
-            Union[str, phonenumbers.PhoneNumber],
-            PhoneNumberValidator(supported_regions=['US'], default_region='US')
+            Union[str, phonenumbers.PhoneNumber], PhoneNumberValidator(supported_regions=['US'], default_region='US')
         ]
 
+
         class SomeModel(BaseModel):
             phone_number: MyNumberType
             us_number: USNumberType
+        ```
     """
 
     default_region: str | None = None
+    """The default region code to use when parsing phone numbers without an international prefix.
+
+    If `None` (the default), the region must be supplied in the phone number as an international prefix.
+    """
+
     number_format: str = 'RFC3966'
+    """The format of the phone number to return. See `phonenumbers.PhoneNumberFormat` for valid values."""
+
     supported_regions: Sequence[str] | None = None
+    """The supported regions. If empty (the default), all regions are supported."""
 
     def __post_init__(self) -> None:
         if self.default_region and self.default_region not in phonenumbers.SUPPORTED_REGIONS: