Repository: sktime/sktime
Pull request: [DOC] Document `evaluate` output DataFrame schema 
<!--
Thanks for contributing a pull request! Please ensure you have taken a look
at our contribution guide: https://github.com/sktime/sktime/blob/main/CONTRIBUTING.md
-->

#### Reference Issues/PRs
Closes #3698

#### What does this implement/fix? Explain your changes.
Documents all columns in DataFrame of results returned by `evaluate`

#### Does your contribution introduce a new dependency? If yes, which one?
Np.

#### What should a reviewer concentrate their feedback on?
Docstring.

#### PR checklist
<!--
Please go through the checklist below. Please feel free to remove points if they are not applicable.
-->

##### For all contributions
- [x] I've added myself to the [list of contributors](https://github.com/sktime/sktime/blob/main/.all-contributorsrc).
- [x] The PR title starts with either [ENH], [MNT], [DOC], or [BUG] indicating whether the PR topic is related to enhancement, maintenance, documentation, or bug.

<!--
Thanks for contributing!
-->


Problem statement:
[DOC] `pd.DataFrame` output schema of `evaluate` needs to be documented properly in docstring
The docstring of `evaluate` in the `forecasting.model_evaluation` module only tells the user that the return is `pd.DataFrame` without further description of the schema.

Best way to glean the schema is to run the example; alternatively, the schema is tested by calls to `_check_evaluate_output` in the tests.

Hints from issue discussion:

Commit message: Update return signature docs

Patch to review:
diff --git a/sktime/forecasting/model_evaluation/_functions.py b/sktime/forecasting/model_evaluation/_functions.py
index 4bf258207a5..c799d82f9df 100644
--- a/sktime/forecasting/model_evaluation/_functions.py
+++ b/sktime/forecasting/model_evaluation/_functions.py
@@ -263,9 +263,18 @@ def evaluate(
 
     Returns
     -------
-    pd.DataFrame
+    results : pd.DataFrame or dask.dataframe.DataFrame
         DataFrame that contains several columns with information regarding each
         refit/update and prediction of the forecaster.
+        Returned DataFrame contains following columns:
+        - test_{scoring.name}: (float) Model performance scores.
+        - fit_time: (float) Time in seconds to fit estimator on train window.
+        - pred_time: (float) Time in seconds to get forecasts from fitted estimator.
+        - len_train_window: (int) Length of train window.
+        - cutoff: (int, pd.Timestamp, pd.Period) Last time point of train window.
+        - y_train: (pd.Series) Optional; see `return_data`.
+        - y_pred: (pd.Series) Optional; see `return_data`.
+        - y_test: (pd.Series) Optional; see `return_data`.
 
     Examples
     --------
@@ -338,7 +347,7 @@ def evaluate(
             )
         X = convert_to(X, to_type=PANDAS_MTYPES)
 
-    score_name = "test_" + scoring.name
+    score_name = f"test_{scoring.name}"
     cutoff_dtype = str(y.index.dtype)
     _evaluate_window_kwargs = {
         "fh": cv.fh,


Code review comments:
diff_hunk: @@ -263,9 +263,18 @@ def evaluate(
 
     Returns
     -------
-    pd.DataFrame
+    results : pd.DataFrame or dask.dataframe.DataFrame
         DataFrame that contains several columns with information regarding each
         refit/update and prediction of the forecaster.
+        Returned DataFrame contains following columns:
path: sktime/forecasting/model_evaluation/_functions.py
text: @user1:
contains -> has

diff_hunk: @@ -263,9 +263,18 @@ def evaluate(
 
     Returns
     -------
-    pd.DataFrame
+    results : pd.DataFrame or dask.dataframe.DataFrame
         DataFrame that contains several columns with information regarding each
         refit/update and prediction of the forecaster.
+        Returned DataFrame contains following columns:
+        - test_{scoring.name}: (float) Model performance scores.
+        - fit_time: (float) Time in seconds to fit estimator on train window.
+        - pred_time: (float) Time in seconds to get forecasts from fitted estimator.
+        - len_train_window: (int) Length of train window.
+        - cutoff: (int, pd.Timestamp, pd.Period) Last time point of train window.
+        - y_train: (pd.Series) Optional; see `return_data`.
path: sktime/forecasting/model_evaluation/_functions.py
text: @author:
```suggestion
        - y_train: (pd.Series) Optional, see `return_data`; data used to train forecaster at n-th window.
```