From 2321565d6904eab2b2898e7d5d2ab6f698b25611 Mon Sep 17 00:00:00 2001
From: Francois Chollet <fchollet@google.com>
Date: Fri, 19 Mar 2021 14:49:51 -0700
Subject: [PATCH] Improve docstring of `History` callback.

PiperOrigin-RevId: 363975387
---
 keras/callbacks.py | 29 ++++++++++++++++++++---------
 1 file changed, 20 insertions(+), 9 deletions(-)

diff --git a/keras/callbacks.py b/keras/callbacks.py
index 34c28971dd93..eda539ae701f 100644
--- a/keras/callbacks.py
+++ b/keras/callbacks.py
@@ -1086,22 +1086,33 @@ def _finalize_progbar(self, logs, counter):
 class History(Callback):
   """Callback that records events into a `History` object.
 
-  This callback is automatically applied to
-  every Keras model. The `History` object
-  gets returned by the `fit` method of models.
+  This callback gets added by default to
+  every call of `model.fit()`. That's how Keras keeps track of model training
+  history. You should never have to add this callback manually.
+
+  The `History` callback instance that is automatically added to `fit()`
+  gets returned at the end of `fit()`.
+  This `History` instance contains a `.history` attribute, which is a dict
+  that stores the logs of the model, such as the loss values for each
+  training epoch.
 
   Example:
 
   >>> model = tf.keras.models.Sequential([tf.keras.layers.Dense(10)])
-  >>> model.compile(tf.keras.optimizers.SGD(), loss='mse')
-  >>> history = model.fit(np.arange(100).reshape(5, 20), np.zeros(5),
-  ...                     epochs=10)
+  >>> model.compile(optimizer='sgd', loss='mse')
+  >>> history = model.fit(np.zeros((32, 5)), np.zeros((32, 10)),
+  ...                     epochs=5)
+  >>> # Inspect training parameters
   >>> print(history.params)
-  {'verbose': 1, 'epochs': 10, 'steps': 1}
-  >>> # check the keys of history object
+  {'verbose': 1, 'epochs': 5, 'steps': 1}
+  >>> # Inspect the keys of the `history` dict
   >>> print(history.history.keys())
   dict_keys(['loss'])
-
+  >>> print(history.history.keys())
+  dict_keys(['loss'])
+  >>> # This is the loss history over the 5 training epochs
+  >>> history.history['loss']
+  [0.0, 0.0, 0.0, 0.0, 0.0]
   """
 
   def __init__(self):