DOC : Update the Period.dayofweek/Period.weekday docstring (#20413)

Author: IHackPy

pandas/_libs/tslibs/period.pyx

@@ -54,7 +54,6 @@ from offsets import _Tick
 
 cdef bint PY2 = str == bytes
 
-
 cdef extern from "period_helper.h":
     int FR_ANN
     int FR_QTR
@@ -1380,41 +1379,105 @@ cdef class _Period(object):
     @property
     def dayofweek(self):
         """
-        Return the day of the week.
+        Day of the week the period lies in, with Monday=0 and Sunday=6.
+
+        If the period frequency is lower than daily (e.g. hourly), and the
+        period spans over multiple days, the day at the start of the period is
+        used.
 
-        This attribute returns the day of the week on which the particular
-        date for the given period occurs depending on the frequency with
-        Monday=0, Sunday=6.
+        If the frequency is higher than daily (e.g. monthly), the last day
+        of the period is used.
 
         Returns
         -------
-        Int
-            Range from 0 to 6 (included).
+        int
+            Day of the week.
 
-        See also
+        See Also
         --------
-        Period.dayofyear : Return the day of the year.
-        Period.daysinmonth : Return the number of days in that month.
+        Period.dayofweek : Day of the week the period lies in.
+        Period.weekday : Alias of Period.dayofweek.
+        Period.day : Day of the month.
+        Period.dayofyear : Day of the year.
 
         Examples
         --------
-        >>> period1 = pd.Period('2012-1-1 19:00', freq='H')
-        >>> period1
-        Period('2012-01-01 19:00', 'H')
-        >>> period1.dayofweek
+        >>> per = pd.Period('2017-12-31 22:00', 'H')
+        >>> per.dayofweek
+        6
+
+        For periods that span over multiple days, the day at the beginning of
+        the period is returned.
+
+        >>> per = pd.Period('2017-12-31 22:00', '4H')
+        >>> per.dayofweek
+        6
+        >>> per.start_time.dayofweek
         6
 
-        >>> period2 = pd.Period('2013-1-9 11:00', freq='H')
-        >>> period2
-        Period('2013-01-09 11:00', 'H')
-        >>> period2.dayofweek
+        For periods with a frequency higher than days, the last day of the
+        period is returned.
+
+        >>> per = pd.Period('2018-01', 'M')
+        >>> per.dayofweek
+        2
+        >>> per.end_time.dayofweek
         2
         """
         base, mult = get_freq_code(self.freq)
         return pweekday(self.ordinal, base)
 
     @property
     def weekday(self):
+        """
+        Day of the week the period lies in, with Monday=0 and Sunday=6.
+
+        If the period frequency is lower than daily (e.g. hourly), and the
+        period spans over multiple days, the day at the start of the period is
+        used.
+
+        If the frequency is higher than daily (e.g. monthly), the last day
+        of the period is used.
+
+        Returns
+        -------
+        int
+            Day of the week.
+
+        See Also
+        --------
+        Period.dayofweek : Day of the week the period lies in.
+        Period.weekday : Alias of Period.dayofweek.
+        Period.day : Day of the month.
+        Period.dayofyear : Day of the year.
+
+        Examples
+        --------
+        >>> per = pd.Period('2017-12-31 22:00', 'H')
+        >>> per.dayofweek
+        6
+
+        For periods that span over multiple days, the day at the beginning of
+        the period is returned.
+
+        >>> per = pd.Period('2017-12-31 22:00', '4H')
+        >>> per.dayofweek
+        6
+        >>> per.start_time.dayofweek
+        6
+
+        For periods with a frequency higher than days, the last day of the
+        period is returned.
+
+        >>> per = pd.Period('2018-01', 'M')
+        >>> per.dayofweek
+        2
+        >>> per.end_time.dayofweek
+        2
+        """
+        # Docstring is a duplicate from dayofweek. Reusing docstrings with
+        # Appender doesn't work for properties in Cython files, and setting
+        # the __doc__ attribute is also not possible.
         return self.dayofweek
 
     @property