DOC: Clarify note on date_range/timedelta_range arguments

Author: sachinn854

pandas/core/indexes/datetimes.py

@@ -836,176 +836,56 @@ def date_range(
     """
     Return a fixed frequency DatetimeIndex.
 
-    Returns the range of equally spaced time points (where the difference between any
-    two adjacent points is specified by the given frequency) such that they fall in the
-    range `[start, end]` , where the first one and the last one are, resp., the first
-    and last time points in that range that fall on the boundary of ``freq`` (if given
-    as a frequency string) or that are valid for ``freq`` (if given as a
-    :class:`pandas.tseries.offsets.DateOffset`). If ``freq`` is positive, the points
-    satisfy `start <[=] x <[=] end`, and if ``freq`` is negative, the points satisfy
-    `end <[=] x <[=] start`. (If exactly one of ``start``, ``end``, or ``freq`` is *not*
-    specified, this missing parameter can be computed given ``periods``, the number of
-    timesteps in the range. See the note below.)
+    :param start: Left bound for generating dates. Accepts string or datetime-like object. Optional.
+    :type start: str or datetime-like, optional
 
-    Parameters
-    ----------
-    start : str or datetime-like, optional
-        Left bound for generating dates.
-    end : str or datetime-like, optional
-        Right bound for generating dates.
-    periods : int, optional
-        Number of periods to generate.
-    freq : str, Timedelta, datetime.timedelta, or DateOffset, default 'D'
-        Frequency strings can have multiples, e.g. '5h'. See
-        :ref:`here <timeseries.offset_aliases>` for a list of
-        frequency aliases.
-    tz : str or tzinfo, optional
-        Time zone name for returning localized DatetimeIndex, for example
-        'Asia/Hong_Kong'. By default, the resulting DatetimeIndex is
-        timezone-naive unless timezone-aware datetime-likes are passed.
-    normalize : bool, default False
-        Normalize start/end dates to midnight before generating date range.
-    name : str, default None
-        Name of the resulting DatetimeIndex.
-    inclusive : {"both", "neither", "left", "right"}, default "both"
-        Include boundaries; Whether to set each bound as closed or open.
+    :param end: Right bound for generating dates. Accepts string or datetime-like object. Optional.
+    :type end: str or datetime-like, optional
 
-        .. versionadded:: 1.4.0
-    unit : str, default None
-        Specify the desired resolution of the result.
+    :param periods: Number of periods to generate. Mutually exclusive with one of `start` or `end`. Optional.
+    :type periods: int, optional
 
-        .. versionadded:: 2.0.0
-    **kwargs
-        For compatibility. Has no effect on the result.
+    :param freq: Frequency string or offset. Determines the spacing between dates. Defaults to 'D' (day) if not specified and enough information is provided. Accepts string (e.g., '5h'), Timedelta, datetime.timedelta, or DateOffset.
+    :type freq: str, Timedelta, datetime.timedelta, or DateOffset, optional
 
-    Returns
-    -------
-    DatetimeIndex
-        A DatetimeIndex object of the generated dates.
+    :param tz: Time zone name or tzinfo to localize the DatetimeIndex. If not specified, the result is timezone-naive unless timezone-aware inputs are provided.
+    :type tz: str or tzinfo, optional
 
-    See Also
-    --------
-    DatetimeIndex : An immutable container for datetimes.
-    timedelta_range : Return a fixed frequency TimedeltaIndex.
-    period_range : Return a fixed frequency PeriodIndex.
-    interval_range : Return a fixed frequency IntervalIndex.
+    :param normalize: Whether to normalize start/end dates to midnight before generating the date range.
+    :type normalize: bool, default False
 
-    Notes
-    -----
-    Of the four parameters ``start``, ``end``, ``periods``, and ``freq``,
-    exactly three must be specified. If ``freq`` is omitted, the resulting
-    ``DatetimeIndex`` will have ``periods`` linearly spaced elements between
-    ``start`` and ``end`` (closed on both sides).
+    :param name: Name to assign to the resulting DatetimeIndex.
+    :type name: str, optional
 
-    To learn more about the frequency strings, please see
-    :ref:`this link<timeseries.offset_aliases>`.
+    :param inclusive: Whether to include boundaries. One of {"both", "neither", "left", "right"}. Default is "both".
+    :type inclusive: {"both", "neither", "left", "right"}, default "both"
 
-    Examples
-    --------
-    **Specifying the values**
-
-    The next four examples generate the same `DatetimeIndex`, but vary
-    the combination of `start`, `end` and `periods`.
-
-    Specify `start` and `end`, with the default daily frequency.
-
-    >>> pd.date_range(start="1/1/2018", end="1/08/2018")
-    DatetimeIndex(['2018-01-01', '2018-01-02', '2018-01-03', '2018-01-04',
-                   '2018-01-05', '2018-01-06', '2018-01-07', '2018-01-08'],
-                  dtype='datetime64[ns]', freq='D')
-
-    Specify timezone-aware `start` and `end`, with the default daily frequency.
-
-    >>> pd.date_range(
-    ...     start=pd.to_datetime("1/1/2018").tz_localize("Europe/Berlin"),
-    ...     end=pd.to_datetime("1/08/2018").tz_localize("Europe/Berlin"),
-    ... )
-    DatetimeIndex(['2018-01-01 00:00:00+01:00', '2018-01-02 00:00:00+01:00',
-                   '2018-01-03 00:00:00+01:00', '2018-01-04 00:00:00+01:00',
-                   '2018-01-05 00:00:00+01:00', '2018-01-06 00:00:00+01:00',
-                   '2018-01-07 00:00:00+01:00', '2018-01-08 00:00:00+01:00'],
-                  dtype='datetime64[ns, Europe/Berlin]', freq='D')
-
-    Specify `start` and `periods`, the number of periods (days).
-
-    >>> pd.date_range(start="1/1/2018", periods=8)
-    DatetimeIndex(['2018-01-01', '2018-01-02', '2018-01-03', '2018-01-04',
-                   '2018-01-05', '2018-01-06', '2018-01-07', '2018-01-08'],
-                  dtype='datetime64[ns]', freq='D')
-
-    Specify `end` and `periods`, the number of periods (days).
-
-    >>> pd.date_range(end="1/1/2018", periods=8)
-    DatetimeIndex(['2017-12-25', '2017-12-26', '2017-12-27', '2017-12-28',
-                   '2017-12-29', '2017-12-30', '2017-12-31', '2018-01-01'],
-                  dtype='datetime64[ns]', freq='D')
-
-    Specify `start`, `end`, and `periods`; the frequency is generated
-    automatically (linearly spaced).
+    :param unit: Specify the desired resolution of the result (e.g., 's' for seconds).
+    :type unit: str, optional
 
-    >>> pd.date_range(start="2018-04-24", end="2018-04-27", periods=3)
-    DatetimeIndex(['2018-04-24 00:00:00', '2018-04-25 12:00:00',
-                   '2018-04-27 00:00:00'],
-                  dtype='datetime64[ns]', freq=None)
+    :param kwargs: Additional keyword arguments for compatibility. Has no effect on the result.
 
-    **Other Parameters**
+    :return: DatetimeIndex of the generated dates.
+    :rtype: DatetimeIndex
 
-    Changed the `freq` (frequency) to ``'ME'`` (month end frequency).
+    :raises ValueError: If less than three of the four parameters (`start`, `end`, `periods`, `freq`) are specified.
 
-    >>> pd.date_range(start="1/1/2018", periods=5, freq="ME")
-    DatetimeIndex(['2018-01-31', '2018-02-28', '2018-03-31', '2018-04-30',
-                   '2018-05-31'],
-                  dtype='datetime64[ns]', freq='ME')
+    .. note::
+        Of the four parameters (`start`, `end`, `periods`, `freq`), exactly three must be specified. If `freq` is omitted, the resulting DatetimeIndex will have `periods` linearly spaced elements between `start` and `end` (inclusive or exclusive depending on `inclusive`).
 
-    Multiples are allowed
+    .. seealso::
+        :class:`pandas.DatetimeIndex` : Immutable container for datetimes.
+        :func:`pandas.timedelta_range` : Return a fixed frequency TimedeltaIndex.
+        :func:`pandas.period_range` : Return a fixed frequency PeriodIndex.
+        :func:`pandas.interval_range` : Return a fixed frequency IntervalIndex.
 
-    >>> pd.date_range(start="1/1/2018", periods=5, freq="3ME")
-    DatetimeIndex(['2018-01-31', '2018-04-30', '2018-07-31', '2018-10-31',
-                   '2019-01-31'],
-                  dtype='datetime64[ns]', freq='3ME')
-
-    `freq` can also be specified as an Offset object.
-
-    >>> pd.date_range(start="1/1/2018", periods=5, freq=pd.offsets.MonthEnd(3))
-    DatetimeIndex(['2018-01-31', '2018-04-30', '2018-07-31', '2018-10-31',
-                   '2019-01-31'],
-                  dtype='datetime64[ns]', freq='3ME')
-
-    Specify `tz` to set the timezone.
-
-    >>> pd.date_range(start="1/1/2018", periods=5, tz="Asia/Tokyo")
-    DatetimeIndex(['2018-01-01 00:00:00+09:00', '2018-01-02 00:00:00+09:00',
-                   '2018-01-03 00:00:00+09:00', '2018-01-04 00:00:00+09:00',
-                   '2018-01-05 00:00:00+09:00'],
-                  dtype='datetime64[ns, Asia/Tokyo]', freq='D')
-
-    `inclusive` controls whether to include `start` and `end` that are on the
-    boundary. The default, "both", includes boundary points on either end.
-
-    >>> pd.date_range(start="2017-01-01", end="2017-01-04", inclusive="both")
-    DatetimeIndex(['2017-01-01', '2017-01-02', '2017-01-03', '2017-01-04'],
-                  dtype='datetime64[ns]', freq='D')
-
-    Use ``inclusive='left'`` to exclude `end` if it falls on the boundary.
-
-    >>> pd.date_range(start="2017-01-01", end="2017-01-04", inclusive="left")
-    DatetimeIndex(['2017-01-01', '2017-01-02', '2017-01-03'],
-                  dtype='datetime64[ns]', freq='D')
-
-    Use ``inclusive='right'`` to exclude `start` if it falls on the boundary, and
-    similarly ``inclusive='neither'`` will exclude both `start` and `end`.
-
-    >>> pd.date_range(start="2017-01-01", end="2017-01-04", inclusive="right")
-    DatetimeIndex(['2017-01-02', '2017-01-03', '2017-01-04'],
-                  dtype='datetime64[ns]', freq='D')
-
-    **Specify a unit**
+    Examples
+    --------
+    >>> pd.date_range(start="2020-01-01", end="2020-01-05")
+    DatetimeIndex(['2020-01-01', '2020-01-02', '2020-01-03', '2020-01-04', '2020-01-05'], dtype='datetime64[ns]', freq='D')
 
-    >>> pd.date_range(start="2017-01-01", periods=10, freq="100YS", unit="s")
-    DatetimeIndex(['2017-01-01', '2117-01-01', '2217-01-01', '2317-01-01',
-                   '2417-01-01', '2517-01-01', '2617-01-01', '2717-01-01',
-                   '2817-01-01', '2917-01-01'],
-                  dtype='datetime64[s]', freq='100YS-JAN')
+    >>> pd.date_range(start="2020-01-01", periods=3, freq="2D")
+    DatetimeIndex(['2020-01-01', '2020-01-03', '2020-01-05'], dtype='datetime64[ns]', freq='2D')
     """
     if freq is None and com.any_none(periods, start, end):
         freq = "D"