[WIP] Mention of pairwise_distances in Guide on Metrics
diff --git a/doc/modules/metrics.rst b/doc/modules/metrics.rst
index 0c3d255d3b134..e1bb6931fb95d 100644
--- a/doc/modules/metrics.rst
+++ b/doc/modules/metrics.rst
@@ -33,6 +33,34 @@ the kernel:
     2. ``S = 1. / (D / np.max(D))``
 
 
+.. currentmodule:: sklearn.metrics
+
+The distances between the row vectors of ``X`` and the row vectors of ``Y``
+can be evaluated using :func:`pairwise_distances`. If ``Y`` is omitted the
+pairwise distances of the row vectors of ``X`` are calculated. Similarly,
+:func:`pairwise.pairwise_kernels` can be used to calculate the kernel between `X`
+and `Y` using different kernel functions. See the API reference for more
+details.
+
+    >>> import numpy as np
+    >>> from sklearn.metrics import pairwise_distances
+    >>> from sklearn.metrics.pairwise import pairwise_kernels
+    >>> X = np.array([[2, 3], [3, 5], [5, 8]])
+    >>> Y = np.array([[1, 0], [2, 1]])
+    >>> pairwise_distances(X, Y, metric='manhattan')
+    array([[ 4.,  2.],
+           [ 7.,  5.],
+           [12., 10.]])
+    >>> pairwise_distances(X, metric='manhattan')
+    array([[0., 3., 8.],
+           [3., 0., 5.],
+           [8., 5., 0.]])
+    >>> pairwise_kernels(X, Y, metric='linear')
+    array([[ 2.,  7.],
+           [ 3., 11.],
+           [ 5., 18.]])
+
+
 .. currentmodule:: sklearn.metrics.pairwise
 
 .. _cosine_similarity:

#### Reference Issues/PRs
Fixes #9428.

#### What does this implement/fix? Explain your changes.

Section [4.8. Pairwise metrics, Affinities and Kernels](http://scikit-learn.org/stable/modules/metrics.html) of the guide talks about "evaluate pairwise distances" but does not mention the functions `pairwise_distances` or `pairwise_kernels`.

This hint with some example code has been added.
