From cce2f66b3ce82979d143f57e8ba1656957538073 Mon Sep 17 00:00:00 2001
From: Natalia Mokeeva <91160475+natmokval@users.noreply.github.com>
Date: Wed, 12 Jun 2024 18:50:15 +0200
Subject: [PATCH] DOC: add examples to clarify the behavior of `is_year_start`
 for business offsets (#58975)

* add examples to is_year_start

* add missing spaces

* remove unnecessary spaces

* add missing parentheses

* update is_year_start example
---
 pandas/core/arrays/datetimes.py | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)

diff --git a/pandas/core/arrays/datetimes.py b/pandas/core/arrays/datetimes.py
index 077bde35a4c94..e0a4587535cfd 100644
--- a/pandas/core/arrays/datetimes.py
+++ b/pandas/core/arrays/datetimes.py
@@ -2119,6 +2119,32 @@ def isocalendar(self) -> DataFrame:
 
         >>> idx.is_year_start
         array([False, False,  True])
+
+        This method, when applied to Series with datetime values under
+        the ``.dt`` accessor, will lose information about Business offsets.
+
+        >>> dates = pd.Series(pd.date_range("2020-10-30", periods=4, freq="BYS"))
+        >>> dates
+        0   2021-01-01
+        1   2022-01-03
+        2   2023-01-02
+        3   2024-01-01
+        dtype: datetime64[ns]
+
+        >>> dates.dt.is_year_start
+        0    True
+        1    False
+        2    False
+        3    True
+        dtype: bool
+
+        >>> idx = pd.date_range("2020-10-30", periods=4, freq="BYS")
+        >>> idx
+        DatetimeIndex(['2021-01-01', '2022-01-03', '2023-01-02', '2024-01-01'],
+                      dtype='datetime64[ns]', freq='BYS-JAN')
+
+        >>> idx.is_year_start
+        array([ True,  True,  True,  True])
         """,
     )
     is_year_end = _field_accessor(