DOC: Add experimental note to DatetimeArray and TimedeltaArray

DOC: Mention PeriodArray and IntervalArray

Closes #24870

Author: TomAugspurger

doc/source/whatsnew/v0.24.0.rst

@@ -210,6 +210,9 @@ from the ``Series``:
    ser.array
    pser.array
 
+These return an instance of :class:`IntervalArray` or :class:`arrays.PeriodArray`,
+the new extension arrays that back interval and period data.
+
 .. warning::
 
    For backwards compatibility, :attr:`Series.values` continues to return

pandas/core/arrays/datetimes.py

@@ -218,6 +218,12 @@ class DatetimeArray(dtl.DatetimeLikeArrayMixin,
 
     .. versionadded:: 0.24.0
 
+    .. warning::
+
+       DatetimeArray is currently experimental, and its API may change
+       without warning. In particular, :meth:`DatetimeArray.dtype` is
+       expected to change to always be an ``ExtensionDtype``.
+
     Parameters
     ----------
     values : Series, Index, DatetimeArray, ndarray
@@ -511,6 +517,12 @@ def dtype(self):
         """
         The dtype for the DatetimeArray.
 
+        .. warning::
+
+           A future version of pandas will change dtype to never be a
+           ``numpy.dtype``. Instead it will always be a subclass of
+           :class:`pandas.api.extensions.ExtensionDtype`.
+
         Returns
         -------
         numpy.dtype or DatetimeTZDtype

pandas/core/arrays/timedeltas.py

@@ -107,6 +107,28 @@ def wrapper(self, other):
 
 
 class TimedeltaArray(dtl.DatetimeLikeArrayMixin, dtl.TimelikeOps):
+    """
+    Pandas ExtensionArray for timedelta data.
+
+    .. versionadded :: 0.24.0
+
+    .. warning::
+
+       TimedeltaArray is currently experimental, and its API may change
+       without warning. In particular, :meth:`TimedeltaArray.dtype` is
+       expected to change to be an ``ExtensionDtype``.
+
+    Parameters
+    ----------
+    values : array-like
+        The timedelta data.
+
+    dtype : numpy.dtype
+        Currently, only ``numpy.dtype("timedelta64[ns]")`` is accepted.
+    freq : Offset, optional
+    copy : bool, default False
+        Whether to copy the underlying array of data.
+    """
     _typ = "timedeltaarray"
     _scalar_type = Timedelta
     __array_priority__ = 1000
@@ -128,6 +150,19 @@ def _box_func(self):
 
     @property
     def dtype(self):
+        """
+        The dtype for the TimedeltaArray.
+
+        .. warning::
+
+           A future version of pandas will change dtype to be an instance
+           of a :class:`pandas.api.extensions.ExtensionDtype` subclass,
+           not a ``numpy.dtype``.
+
+        Returns
+        -------
+        numpy.dtype
+        """
         return _TD_DTYPE
 
     # ----------------------------------------------------------------