[FLINK-4047] [docs] Fix documentation about determinism of KeySelectors

This closes #4659.

docs/dev/api_concepts.md

@@ -450,7 +450,7 @@ These are valid field expressions for the example code above:
 {:.no_toc}
 
 An additional way to define keys are "key selector" functions. A key selector function
-takes a single element as input and returns the key for the element. The key can be of any type and be derived from arbitrary computations.
+takes a single element as input and returns the key for the element. The key can be of any type and be derived from deterministic computations.
 
 The following example shows a key selector function that simply returns the field of an object:
 

flink-core/src/main/java/org/apache/flink/api/java/functions/KeySelector.java

@@ -24,10 +24,11 @@ import org.apache.flink.api.common.functions.Function;
 import java.io.Serializable;
 
 /**
- * The {@link KeySelector} allows to use arbitrary objects for operations such as
- * reduce, reduceGroup, join, coGoup, etc.
+ * The {@link KeySelector} allows to use deterministic objects for operations such as
+ * reduce, reduceGroup, join, coGoup, etc. If invoked multiple times on the same object,
+ * the returned key must be the same.
  * 
- * The extractor takes an object and returns the key for that object.
+ * The extractor takes an object and returns the deterministic key for that object.
  *
  * @param <IN> Type of objects to extract the key from.
  * @param <KEY> Type of key.
@@ -36,7 +37,7 @@ import java.io.Serializable;
 public interface KeySelector<IN, KEY> extends Function, Serializable {
 
 	/**
-	 * User-defined function that extracts the key from an arbitrary object.
+	 * User-defined function that deterministically extracts the key from an object.
 	 * 
 	 * For example for a class:
 	 * <pre>