[python-package] clarify max_depth warning and limit when it is emitted

[jameslamb]

fixes #2898
fixes #5734

Modifies a warning that has historically been confusing for some LightGBM users. @shiyu1994 explained it very well in #2898 (comment):

The warning message is actually saying: "you forget to set num_leaves, but you've set max_depth"...because LightGBM has a default num_leaves=31, the warning message reminds the user to set num_leaves accordingly when setting max_depth.

This PR proposes an implementation of @shiyu1994 's proposal from further down in that comment.

keep the document unchanged. But in config.cpp... detect whether num_leaves is set by user (instead of simply checking whether it is ==31, since user can also set it to 31). And if num_leaves is not set but max_depth is set, we may produce a warning...

As a side effect of this change, that also means the warning in question will never be raised from the scikit-learn estimators. They always pass num_leaves in params, from this keyword argument:

LightGBM/python-package/lightgbm/sklearn.py

Line 463 in 28536a0

num_leaves: int = 31,

I think that's ok. We have the docs in https://lightgbm.readthedocs.io/en/latest/Parameters-Tuning.html#tune-parameters-for-the-leaf-wise-best-first-tree. I'd rather have the scikit-learn estimators not emit this warning than take on the added complexity that'd be required to detect whether or not num_leaves was explicitly provided in the constructor keyword args.

Notes for Reviewers

I would really like a review from @shiyu1994, to be sure I've interpreted #2898 (comment) correctly.

Would also appreciate feedback from any of the people involved in the previous discussions about this one whether this new warning is clearer.

[Warning] Provided parameters constrain tree depth (max_depth=8) without explicitly setting 'num_leaves'.
This can lead to underfitting. To resolve this warning, pass 'num_leaves' (<=256) in params.
Alternatively, pass (max_depth=-1) and just use 'num_leaves' to constrain model complexity.

cc @bfrobin446 @AlbertoEAF @dxyzx0 @aEgoist @memeplex @Wang-Yu-Qing @Cat2Li

[jameslamb]

params here contains the content of what was passed through by the used (with aliases already resolved). So it can be used to differentiate between "user code passed num_leaves=31" and "num_leaves=31 because that's the default and user didn't pass any value for it".

[borchero]

Makes sense to me! A few small comments... 😄

[shiyu1994]

I'll review this tomorrow. Thanks.

[borchero]

LGTM! (modulo linting CI job 😄)

[jameslamb]

@shiyu1994 could you please review this this week?

[shiyu1994]

Looks good to me. Thank you for the change.