DOC improve cross_val_predict docs
@@ -627,8 +627,14 @@ def cross_val_predict(estimator, X, y=None, groups=None, cv=None,
pre_dispatch='2*n_jobs', method='predict'):
"""Generate cross-validated estimates for each input data point
- It is not appropriate to pass these predictions into an evaluation
- metric. Use :func:`cross_validate` to measure generalization error.
+ The data is split according to the cv parameter. Each sample belongs
+ to exactly one test set, and its prediction is computed with an
+ estimator fitted on the corresponding training set.
+
+ Passing these predictions into an evaluation metric may not be a valid
+ way to measure generalization performance. Results can differ from
+ `cross_validate` and `cross_val_score` unless all tests sets have equal
+ size and the metric decomposes over samples.
Read more in the :ref:`User Guide <cross_validation>`.
