From ca1230561905f067204e3bfdd5f75d1ab5b88377 Mon Sep 17 00:00:00 2001
From: tdang2k <lamdan0008@gmail.com>
Date: Sun, 25 Feb 2024 00:42:42 +0100
Subject: [PATCH 1/3] Add docstrings to timedeltas.pyx

---
 ci/code_checks.sh                  |  3 --
 pandas/_libs/tslibs/timedeltas.pyx | 54 ++++++++++++++++++++++++++++++
 2 files changed, 54 insertions(+), 3 deletions(-)

diff --git a/ci/code_checks.sh b/ci/code_checks.sh
index 231d40e17c0c0..a8d1c9d8df056 100755
--- a/ci/code_checks.sh
+++ b/ci/code_checks.sh
@@ -165,9 +165,6 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then
         pandas.Series.dt.qyear\
         pandas.Series.dt.unit\
         pandas.Series.empty\
-        pandas.Timedelta.microseconds\
-        pandas.Timedelta.unit\
-        pandas.Timedelta.value\
         pandas.Timestamp.day\
         pandas.Timestamp.fold\
         pandas.Timestamp.hour\
diff --git a/pandas/_libs/tslibs/timedeltas.pyx b/pandas/_libs/tslibs/timedeltas.pyx
index f6c69cf6d3875..0680ade199a81 100644
--- a/pandas/_libs/tslibs/timedeltas.pyx
+++ b/pandas/_libs/tslibs/timedeltas.pyx
@@ -1038,6 +1038,18 @@ cdef class _Timedelta(timedelta):
 
     @property
     def value(self):
+        """
+        Always return the value of Timedelta object in nanoseconds.
+
+        Returns
+        -------
+        int
+
+        Examples
+        --------
+        >>> pd.Timedelta(1, "us").value
+        1000
+        """
         try:
             return convert_reso(self._value, self._creso, NPY_FR_ns, False)
         except OverflowError:
@@ -1120,6 +1132,35 @@ cdef class _Timedelta(timedelta):
     def microseconds(self) -> int:  # TODO(cython3): make cdef property
         # NB: using the python C-API PyDateTime_DELTA_GET_MICROSECONDS will fail
         #  (or be incorrect)
+        """
+        Return the number of microseconds (n), where 0 <= n < 1 millisecond.
+
+        Returns
+        -------
+        int
+            Number of microseconds.
+
+        See Also
+        --------
+        Timedelta.components : Return all attributes with assigned values
+            (i.e. days, hours, minutes, seconds, milliseconds, microseconds,
+            nanoseconds).
+
+        Examples
+        --------
+        **Using string input**
+
+        >>> td = pd.Timedelta('1 days 2 min 3 us')
+
+        >>> td.microseconds
+        3
+
+        **Using integer input**
+
+        >>> td = pd.Timedelta(42, unit='us')
+        >>> td.microseconds
+        42
+        """
         self._ensure_components()
         return self._ms * 1000 + self._us
 
@@ -1141,6 +1182,19 @@ cdef class _Timedelta(timedelta):
 
     @property
     def unit(self) -> str:
+        """
+        Always return 'ns' as the unit of Timedelta object.
+
+        Returns
+        -------
+        str
+            Unit
+
+        Examples
+        --------
+        >>> td = pd.Timedelta(42, unit='us')
+        'ns'
+        """
         return npy_unit_to_abbrev(self._creso)
 
     def __hash__(_Timedelta self):

From d52e6ee9ff1a80ae2ecb0b32217da655a30ebdba Mon Sep 17 00:00:00 2001
From: tdang2k <lamdan0008@gmail.com>
Date: Sun, 25 Feb 2024 12:45:48 +0100
Subject: [PATCH 2/3] Add extended summary and see also

---
 pandas/_libs/tslibs/timedeltas.pyx | 20 +++++++++++++++++---
 1 file changed, 17 insertions(+), 3 deletions(-)

diff --git a/pandas/_libs/tslibs/timedeltas.pyx b/pandas/_libs/tslibs/timedeltas.pyx
index 0680ade199a81..849da6eedb68c 100644
--- a/pandas/_libs/tslibs/timedeltas.pyx
+++ b/pandas/_libs/tslibs/timedeltas.pyx
@@ -1039,12 +1039,19 @@ cdef class _Timedelta(timedelta):
     @property
     def value(self):
         """
-        Always return the value of Timedelta object in nanoseconds.
+        Return the value of Timedelta object in nanoseconds.
+
+        Return the total seconds, milliseconds and microseconds
+        of the timedelta as nanoseconds.
 
         Returns
         -------
         int
 
+        See Also
+        --------
+        Timedelta.unit : Return the unit of Timedelta object.
+
         Examples
         --------
         >>> pd.Timedelta(1, "us").value
@@ -1135,6 +1142,8 @@ cdef class _Timedelta(timedelta):
         """
         Return the number of microseconds (n), where 0 <= n < 1 millisecond.
 
+        Timedelta.microseconds = milliseconds * 1000 + microseconds.
+
         Returns
         -------
         int
@@ -1183,12 +1192,17 @@ cdef class _Timedelta(timedelta):
     @property
     def unit(self) -> str:
         """
-        Always return 'ns' as the unit of Timedelta object.
+        Return the unit of Timedelta object.
+
+        The unit of Timedelta object is nanosecond, i.e., 'ns' by default.
 
         Returns
         -------
         str
-            Unit
+
+        See Also
+        --------
+        Timedelta.value : Return the value of Timedelta object in nanoseconds.
 
         Examples
         --------

From a47e23e6550a89d3e148cb72f2a8d269b5d8a3af Mon Sep 17 00:00:00 2001
From: tdang2k <lamdan0008@gmail.com>
Date: Tue, 27 Feb 2024 17:55:16 +0100
Subject: [PATCH 3/3] Add as_unit

---
 pandas/_libs/tslibs/timedeltas.pyx | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/pandas/_libs/tslibs/timedeltas.pyx b/pandas/_libs/tslibs/timedeltas.pyx
index 849da6eedb68c..18ead7d5381df 100644
--- a/pandas/_libs/tslibs/timedeltas.pyx
+++ b/pandas/_libs/tslibs/timedeltas.pyx
@@ -1203,6 +1203,8 @@ cdef class _Timedelta(timedelta):
         See Also
         --------
         Timedelta.value : Return the value of Timedelta object in nanoseconds.
+        Timedelta.as_unit : Convert the underlying int64 representation to
+            the given unit.
 
         Examples
         --------