DOC: update the Period.days_in_month docstring (#20297)

* Add doctring for Period.days_in_month

* Update added docstring for Period.days_in_month

* Update added docstring for Period.days_in_month

pandas/_libs/tslibs/period.pyx

@@ -1289,6 +1289,35 @@ cdef class _Period(object):
 
     @property
     def days_in_month(self):
+        """
+        Get the total number of days in the month that this period falls on.
+
+        Returns
+        -------
+        int
+
+        See Also
+        --------
+        Period.daysinmonth : Gets the number of days in the month.
+        DatetimeIndex.daysinmonth : Gets the number of days in the month.
+        calendar.monthrange : Returns a tuple containing weekday
+            (0-6 ~ Mon-Sun) and number of days (28-31).
+
+        Examples
+        --------
+        >>> p = pd.Period('2018-2-17')
+        >>> p.days_in_month
+        28
+
+        >>> pd.Period('2018-03-01').days_in_month
+        31
+
+        Handles the leap year case as well:
+
+        >>> p = pd.Period('2016-2-17')
+        >>> p.days_in_month
+        29
+        """
         base, mult = get_freq_code(self.freq)
         return pdays_in_month(self.ordinal, base)