DOC: Add extended summary, update parameter types desc, update return types desc, and add whitespaces after commas in list declarations to DataFrame.first in core/generic.py (#32018)

Co-authored-by: Sang Agung <[email protected]>
Co-authored-by: Marc Garcia <[email protected]>

Author: 3 people

pandas/core/generic.py

@@ -8014,15 +8014,21 @@ def resample(
 
     def first(self: FrameOrSeries, offset) -> FrameOrSeries:
         """
-        Method to subset initial periods of time series data based on a date offset.
+        Select initial periods of time series data based on a date offset.
+
+        When having a DataFrame with dates as index, this function can
+        select the first few rows based on a date offset.
 
         Parameters
         ----------
-        offset : str, DateOffset, dateutil.relativedelta
+        offset : str, DateOffset or dateutil.relativedelta
+            The offset length of the data that will be selected. For instance,
+            '1M' will display all the rows having their index within the first month.
 
         Returns
         -------
-        subset : same type as caller
+        Series or DataFrame
+            A subset of the caller.
 
         Raises
         ------
@@ -8038,7 +8044,7 @@ def first(self: FrameOrSeries, offset) -> FrameOrSeries:
         Examples
         --------
         >>> i = pd.date_range('2018-04-09', periods=4, freq='2D')
-        >>> ts = pd.DataFrame({'A': [1,2,3,4]}, index=i)
+        >>> ts = pd.DataFrame({'A': [1, 2, 3, 4]}, index=i)
         >>> ts
                     A
         2018-04-09  1