DOC: add an example to PeriodIndex.to_timestamp to clarify the behavior in case len(index)<3 (#57384)

* add an example to PeriodIndex.to_timestamp

* correct to_timestamp docs, add an example

* correct the wording in to_timestamp docstring

Author: natmokval

pandas/core/arrays/period.py

@@ -638,6 +638,20 @@ def to_timestamp(self, freq=None, how: str = "start") -> DatetimeArray:
         >>> idx.to_timestamp()
         DatetimeIndex(['2023-01-01', '2023-02-01', '2023-03-01'],
         dtype='datetime64[ns]', freq='MS')
+
+        The frequency will not be inferred if the index contains less than
+        three elements, or if the values of index are not strictly monotonic:
+
+        >>> idx = pd.PeriodIndex(["2023-01", "2023-02"], freq="M")
+        >>> idx.to_timestamp()
+        DatetimeIndex(['2023-01-01', '2023-02-01'], dtype='datetime64[ns]', freq=None)
+
+        >>> idx = pd.PeriodIndex(
+        ...     ["2023-01", "2023-02", "2023-02", "2023-03"], freq="2M"
+        ... )
+        >>> idx.to_timestamp()
+        DatetimeIndex(['2023-01-01', '2023-02-01', '2023-02-01', '2023-03-01'],
+        dtype='datetime64[ns]', freq=None)
         """
         from pandas.core.arrays import DatetimeArray