[docs] corrected misleading note about best_iteration (#1758)

* removed misleading note about best_iteration

* Update engine.py

* Update Python-Intro.rst

* Updated Engine.py

* Updated Python-Intro.rst

* add article 'the best', break huge line and remove excess empty line

docs/Python-Intro.rst

@@ -195,7 +195,7 @@ Early stopping requires at least one set in ``valid_sets``. If there is more tha
 The model will train until the validation score stops improving.
 Validation score needs to improve at least every ``early_stopping_rounds`` to continue training.
 
-If early stopping occurs, the model will have an additional field: ``bst.best_iteration``.
+The index of iteration that has the best performance will be saved in the ``best_iteration`` field if early stopping logic is enabled by setting ``early_stopping_rounds``.
 Note that ``train()`` will return a model from the best iteration.
 
 This works with both metrics to minimize (L2, log loss, etc.) and to maximize (NDCG, AUC, etc.).

python-package/lightgbm/engine.py

@@ -66,8 +66,9 @@ def train(params, train_set, num_boost_round=100,
         to continue training.
         Requires at least one validation data and one metric.
         If there's more than one, will check all of them. But the training data is ignored anyway.
-        If early stopping occurs, the model will add ``best_iteration`` field.
-    evals_result : dict or None, optional (default=None)
+        The index of iteration that has the best performance will be saved in the ``best_iteration`` field
+        if early stopping logic is enabled by setting ``early_stopping_rounds``.
+    evals_result: dict or None, optional (default=None)
         This dictionary used to store all evaluation results of all the items in ``valid_sets``.
 
         Example