DOC: add missing parameters to offsets classes: BYearBegin, YearEnd, YearBegin (pandas-dev#53280)

* DOC: add missing parameters to offsets classes: BYearBegin, YearEnd, YearBegin

* update "get to the end of the year" suggestion to use rollforward instead of rollback

---------

Co-authored-by: Marco Edward Gorelli <[email protected]>

Author: 2 people

pandas/_libs/tslibs/offsets.pyx

@@ -2251,9 +2251,13 @@ cdef class BYearEnd(YearOffset):
         The number of years represented.
     normalize : bool, default False
         Normalize start/end dates to midnight before generating date range.
-    month : int, default 1
+    month : int, default 12
         A specific integer for the month of the year.
 
+    See Also
+    --------
+    :class:`~pandas.tseries.offsets.DateOffset` : Standard kind of date increment.
+
     Examples
     --------
     >>> from pandas.tseries.offsets import BYearEnd
@@ -2280,6 +2284,19 @@ cdef class BYearBegin(YearOffset):
     """
     DateOffset increments between the first business day of the year.
 
+    Parameters
+    ----------
+    n : int, default 1
+        The number of years represented.
+    normalize : bool, default False
+        Normalize start/end dates to midnight before generating date range.
+    month : int, default 1
+        A specific integer for the month of the year.
+
+    See Also
+    --------
+    :class:`~pandas.tseries.offsets.DateOffset` : Standard kind of date increment.
+
     Examples
     --------
     >>> from pandas.tseries.offsets import BYearBegin
@@ -2292,6 +2309,8 @@ cdef class BYearBegin(YearOffset):
     Timestamp('2020-01-01 05:01:15')
     >>> ts + BYearBegin(2)
     Timestamp('2022-01-03 05:01:15')
+    >>> ts + BYearBegin(month=11)
+    Timestamp('2020-11-02 05:01:15')
     """
 
     _outputName = "BusinessYearBegin"
@@ -2306,6 +2325,15 @@ cdef class YearEnd(YearOffset):
 
     YearEnd goes to the next date which is the end of the year.
 
+    Parameters
+    ----------
+    n : int, default 1
+        The number of years represented.
+    normalize : bool, default False
+        Normalize start/end dates to midnight before generating date range.
+    month : int, default 12
+        A specific integer for the month of the year.
+
     See Also
     --------
     :class:`~pandas.tseries.offsets.DateOffset` : Standard kind of date increment.
@@ -2320,10 +2348,14 @@ cdef class YearEnd(YearOffset):
     >>> ts + pd.offsets.YearEnd()
     Timestamp('2023-12-31 00:00:00')
 
+    >>> ts = pd.Timestamp(2022, 1, 1)
+    >>> ts + pd.offsets.YearEnd(month=2)
+    Timestamp('2022-02-28 00:00:00')
+
     If you want to get the end of the current year:
 
     >>> ts = pd.Timestamp(2022, 12, 31)
-    >>> pd.offsets.YearEnd().rollback(ts)
+    >>> pd.offsets.YearEnd().rollforward(ts)
     Timestamp('2022-12-31 00:00:00')
     """
 
@@ -2347,6 +2379,15 @@ cdef class YearBegin(YearOffset):
 
     YearBegin goes to the next date which is the start of the year.
 
+    Parameters
+    ----------
+    n : int, default 1
+        The number of years represented.
+    normalize : bool, default False
+        Normalize start/end dates to midnight before generating date range.
+    month : int, default 1
+        A specific integer for the month of the year.
+
     See Also
     --------
     :class:`~pandas.tseries.offsets.DateOffset` : Standard kind of date increment.
@@ -2361,6 +2402,10 @@ cdef class YearBegin(YearOffset):
     >>> ts + pd.offsets.YearBegin()
     Timestamp('2024-01-01 00:00:00')
 
+    >>> ts = pd.Timestamp(2022, 1, 1)
+    >>> ts + pd.offsets.YearBegin(month=2)
+    Timestamp('2022-02-01 00:00:00')
+
     If you want to get the start of the current year:
 
     >>> ts = pd.Timestamp(2023, 1, 1)