DOC: Fix docstrings for Timestamp: normalize, replace, to_numpy, to_period

ci/code_checks.sh

@@ -195,9 +195,7 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then
         -i "pandas.Timestamp.month GL08" \
         -i "pandas.Timestamp.month_name SA01" \
         -i "pandas.Timestamp.nanosecond GL08" \
-        -i "pandas.Timestamp.normalize SA01" \
         -i "pandas.Timestamp.quarter SA01" \
-        -i "pandas.Timestamp.replace PR07,SA01" \
         -i "pandas.Timestamp.resolution PR02" \
         -i "pandas.Timestamp.second GL08" \
         -i "pandas.Timestamp.strptime PR01,SA01" \
@@ -206,8 +204,6 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then
         -i "pandas.Timestamp.timetz SA01" \
         -i "pandas.Timestamp.to_datetime64 SA01" \
         -i "pandas.Timestamp.to_julian_date SA01" \
-        -i "pandas.Timestamp.to_numpy PR01" \
-        -i "pandas.Timestamp.to_period PR01,SA01" \
         -i "pandas.Timestamp.today SA01" \
         -i "pandas.Timestamp.toordinal SA01" \
         -i "pandas.Timestamp.tzinfo GL08" \

pandas/_libs/tslibs/nattype.pyx

@@ -251,6 +251,13 @@ cdef class _NaT(datetime):
         The copy parameter is available here only for compatibility. Its value
         will not affect the return value.
 
+        Parameters
+        ----------
+        dtype : numpy.dtype, default None
+            Must be None. Otherwise, a ValueError is raised.
+        copy : bool, default False
+            Must be False. Otherwise, a ValueError is raised.
+
         Returns
         -------
         numpy.datetime64 or numpy.timedelta64
@@ -1518,23 +1525,44 @@ default 'raise'
         """
         Implements datetime.replace, handles nanoseconds.
 
+        Returns a new timestamp with the same attributes,
+        except for those given new value.
+
         Parameters
         ----------
         year : int, optional
+            New year value.
         month : int, optional
+            New month value.
         day : int, optional
+            New day value.
         hour : int, optional
+            New hour value.
         minute : int, optional
+            New minute value.
         second : int, optional
+            New second value.
         microsecond : int, optional
+            New microsecond value.
         nanosecond : int, optional
+            New nanosecond value.
         tzinfo : tz-convertible, optional
+            New tzinfo value.
         fold : int, optional
+            New fold value.
 
         Returns
         -------
         Timestamp with fields replaced
 
+        See Also
+        --------
+        Timestamp.normalize : Normalize the Timestamp to midnight,
+            preserving tz information.
+        Timestamp.tz_convert : Convert timezone-aware Timestamp to another time zone.
+        Timestamp.tz_localize : Localize the Timestamp to a timezone.
+        datetime.datetime.replace : Return a new datetime with replaced attributes.
+
         Examples
         --------
         Create a timestamp object:

pandas/_libs/tslibs/timestamps.pyx

@@ -975,7 +975,13 @@ cdef class _Timestamp(ABCTimestamp):
 
     def normalize(self) -> "Timestamp":
         """
-        Normalize Timestamp to midnight, preserving tz information.
+        Normalize Timestamp to previous midnight, preserving tz information.
+
+        This is equivalent to replacing the time part of the timestamp with `00:00:00`.
+
+        See Also
+        --------
+        Timestamp.replace : Return a new timestamp with replaced attributes.
 
         Examples
         --------
@@ -1298,6 +1304,13 @@ cdef class _Timestamp(ABCTimestamp):
         copy parameters are available here only for compatibility. Their values
         will not affect the return value.
 
+        Parameters
+        ----------
+        dtype : numpy.dtype, default None
+            Must be None. Otherwise, a ValueError is raised.
+        copy : bool, default False
+            Must be False. Otherwise, a ValueError is raised.
+
         Returns
         -------
         numpy.datetime64
@@ -1325,7 +1338,24 @@ cdef class _Timestamp(ABCTimestamp):
 
     def to_period(self, freq=None):
         """
-        Return an period of which this timestamp is an observation.
+        Return a period of which this timestamp is an observation.
+
+        This method constructs a `Period` object from the `Timestamp`
+        and provided period.
+        Please note that timezone information will be dropped,
+        since `Period` doesn't support timezones.
+
+        Parameters
+        ----------
+        freq : str, default None
+            The period frequency. Accepted strings are listed in
+            the :ref:`period alias section <timeseries.period_aliases>`
+            in the user docs.
+
+        See Also
+        --------
+        Period : Represents a period of time.
+        Period.to_timestamp : Return the Timestamp representation of the Period.
 
         Examples
         --------
@@ -2687,23 +2717,44 @@ default 'raise'
         """
         Implements datetime.replace, handles nanoseconds.
 
+        Returns a new timestamp with the same attributes,
+        except for those given new value.
+
         Parameters
         ----------
         year : int, optional
+            New year value.
         month : int, optional
+            New month value.
         day : int, optional
+            New day value.
         hour : int, optional
+            New hour value.
         minute : int, optional
+            New minute value.
         second : int, optional
+            New second value.
         microsecond : int, optional
+            New microsecond value.
         nanosecond : int, optional
+            New nanosecond value.
         tzinfo : tz-convertible, optional
+            New tzinfo value.
         fold : int, optional
+            New fold value.
 
         Returns
         -------
         Timestamp with fields replaced
 
+        See Also
+        --------
+        Timestamp.normalize : Normalize the Timestamp to midnight,
+            preserving tz information.
+        Timestamp.tz_convert : Convert timezone-aware Timestamp to another time zone.
+        Timestamp.tz_localize : Localize the Timestamp to a timezone.
+        datetime.datetime.replace : Return a new datetime with replaced attributes.
+
         Examples
         --------
         Create a timestamp object: