[docs] clarified feval parameter (#1488)

python-package/lightgbm/basic.py

@@ -1598,7 +1598,11 @@ class Booster(object):
         name : string
             Name of the data.
         feval : callable or None, optional (default=None)
-            Custom evaluation function.
+            Customized evaluation function.
+            Should accept two parameters: preds, train_data.
+            For multi-class task, the preds is group by class_id first, then group by row_id.
+            If you want to get i-th row preds in j-th class, the access way is preds[j * num_data + i].
+            Note: should return (eval_name, eval_result, is_higher_better) or list of such tuples.
 
         Returns
         -------
@@ -1628,7 +1632,11 @@ class Booster(object):
         Parameters
         ----------
         feval : callable or None, optional (default=None)
-            Custom evaluation function.
+            Customized evaluation function.
+            Should accept two parameters: preds, train_data.
+            For multi-class task, the preds is group by class_id first, then group by row_id.
+            If you want to get i-th row preds in j-th class, the access way is preds[j * num_data + i].
+            Note: should return (eval_name, eval_result, is_higher_better) or list of such tuples.
 
         Returns
         -------
@@ -1643,7 +1651,11 @@ class Booster(object):
         Parameters
         ----------
         feval : callable or None, optional (default=None)
-            Custom evaluation function.
+            Customized evaluation function.
+            Should accept two parameters: preds, train_data.
+            For multi-class task, the preds is group by class_id first, then group by row_id.
+            If you want to get i-th row preds in j-th class, the access way is preds[j * num_data + i].
+            Note: should return (eval_name, eval_result, is_higher_better) or list of such tuples.
 
         Returns
         -------

python-package/lightgbm/engine.py

@@ -41,6 +41,8 @@ def train(params, train_set, num_boost_round=100,
     feval : callable, string or None, optional (default=None)
         Customized evaluation function.
         Should accept two parameters: preds, train_data.
+        For multi-class task, the preds is group by class_id first, then group by row_id.
+        If you want to get i-th row preds in j-th class, the access way is preds[j * num_data + i].
         Note: should return (eval_name, eval_result, is_higher_better) or list of such tuples.
         To ignore the default metric in params, set it to the string ``"None"``
     init_model : string or None, optional (default=None)
@@ -343,8 +345,13 @@ def cv(params, train_set, num_boost_round=100,
         If not None, the metric in ``params`` will be overridden.
     fobj : callable or None, optional (default=None)
         Custom objective function.
-    feval : callable or None, optional (default=None)
-        Custom evaluation function.
+    feval : callable, string or None, optional (default=None)
+        Customized evaluation function.
+        Should accept two parameters: preds, train_data.
+        For multi-class task, the preds is group by class_id first, then group by row_id.
+        If you want to get i-th row preds in j-th class, the access way is preds[j * num_data + i].
+        Note: should return (eval_name, eval_result, is_higher_better) or list of such tuples.
+        To ignore the default metric in params, set it to the string ``"None"``
     init_model : string or None, optional (default=None)
         Filename of LightGBM model or Booster instance used for continue training.
     feature_name : list of strings or 'auto', optional (default="auto")

python-package/lightgbm/sklearn.py

@@ -367,7 +367,7 @@ class LGBMModel(_LGBMModelBase):
                 The weight of samples.
             group: array-like
                 Group/query data, used for ranking task.
-            eval_name: str
+            eval_name: string
                 The name of evaluation.
             eval_result: float
                 The eval result.