Documentation fix: Cosine Similarity

tensorflow/python/keras/losses.py

@@ -1698,8 +1698,8 @@ def cosine_similarity(y_true, y_pred, axis=-1):
   >>> # l2_norm(y_true) = [[0., 1.], [1./1.414], 1./1.414]]]
   >>> # l2_norm(y_pred) = [[1., 0.], [1./1.414], 1./1.414]]]
   >>> # l2_norm(y_true) . l2_norm(y_pred) = [[0., 0.], [0.5, 0.5]]
-  >>> # loss = mean(sum(l2_norm(y_true) . l2_norm(y_pred), axis=1))
-  >>> #       = ((0. + 0.) +  (0.5 + 0.5)) / 2
+  >>> # loss = -sum(l2_norm(y_true) . l2_norm(y_pred), axis=1)
+  >>> #       = -[0. + 0., 0.5 + 0.5]
   >>> loss.numpy()
   array([-0., -0.999], dtype=float32)
 
@@ -1718,9 +1718,16 @@ def cosine_similarity(y_true, y_pred, axis=-1):
 
 @keras_export('keras.losses.CosineSimilarity')
 class CosineSimilarity(LossFunctionWrapper):
-  """Computes the cosine similarity between `y_true` and `y_pred`.
+  """Computes the cosine similarity between labels and predictions.
 
-  `loss = -sum(y_true * y_pred)`
+  Note that it is a negative quantity between -1 and 0, where 0 indicates
+  orthogonality and values closer to -1 indicate greater similarity. This makes
+  it usable as a loss function in a setting where you try to maximize the
+  proximity between predictions and targets. If either `y_true` or `y_pred`
+  is a zero vector, cosine similarity will be 0 regardless of the proximity
+  between predictions and targets.
+
+  `loss = -sum(l2_norm(y_true) * l2_norm(y_pred))`
 
   Usage:
 
@@ -1732,7 +1739,7 @@ class CosineSimilarity(LossFunctionWrapper):
   >>> # l2_norm(y_pred) = [[1., 0.], [1./1.414], 1./1.414]]]
   >>> # l2_norm(y_true) . l2_norm(y_pred) = [[0., 0.], [0.5, 0.5]]
   >>> # loss = mean(sum(l2_norm(y_true) . l2_norm(y_pred), axis=1))
-  >>> #       = ((0. + 0.) +  (0.5 + 0.5)) / 2
+  >>> #       = -((0. + 0.) +  (0.5 + 0.5)) / 2
   >>> cosine_loss(y_true, y_pred).numpy()
   -0.5