DOC: Improve the docstring of Timedelta.asm8 (pandas-dev#21821)

Author: chalmerlowe

pandas/_libs/tslibs/timedeltas.pyx

@@ -834,7 +834,37 @@ cdef class _Timedelta(timedelta):
 
     @property
     def asm8(self):
-        """ return a numpy timedelta64 array view of myself """
+        """
+        Return a numpy timedelta64 array scalar view.
+
+        Provides access to the array scalar view (i.e. a combination of the
+        value and the units) associated with the numpy.timedelta64().view(),
+        including a 64-bit integer representation of the timedelta in
+        nanoseconds (Python int compatible).
+
+        Returns
+        -------
+        numpy timedelta64 array scalar view
+            Array scalar view of the timedelta in nanoseconds.
+
+        Examples
+        --------
+        >>> td = pd.Timedelta('1 days 2 min 3 us 42 ns')
+        >>> td.asm8
+        numpy.timedelta64(86520000003042,'ns')
+
+        >>> td = pd.Timedelta('2 min 3 s')
+        >>> td.asm8
+        numpy.timedelta64(123000000000,'ns')
+
+        >>> td = pd.Timedelta('3 ms 5 us')
+        >>> td.asm8
+        numpy.timedelta64(3005000,'ns')
+
+        >>> td = pd.Timedelta(42, unit='ns')
+        >>> td.asm8
+        numpy.timedelta64(42,'ns')
+        """
         return np.int64(self.value).view('m8[ns]')
 
     @property