docs: Keras 3 evaluate() and compiled metrics clarification (#21506)

* docs: Keras 3 evaluate() and compiled metrics clarification

* Fix docstring formatting

* fix: correct formatting of evaluate() with backticks

Author: sonali-kumari1

keras/src/trainers/trainer.py

@@ -793,8 +793,16 @@ def evaluate(
         Returns:
             Scalar test loss (if the model has a single output and no metrics)
             or list of scalars (if the model has multiple outputs
-            and/or metrics). The attribute `model.metrics_names` will give you
-            the display labels for the scalar outputs.
+            and/or metrics).
+
+        Note: When using compiled metrics, `evaluate()` may return multiple
+        submetric values, while `model.metrics_names` often lists only
+        top-level names (e.g., 'loss', 'compile_metrics'), leading to a
+        length mismatch. The order of the `evaluate()` output corresponds
+        to the order of metrics specified during `model.compile()`. You can
+        use this order to map the `evaluate()` results to the intended
+        metric. `model.metrics_names` itself will still return only the
+        top-level names.
         """
         raise NotImplementedError