[PATCH 1 of 5 modernize-streamclone] exchange: add docstring to pull()

[Gregory Szorc]

# HG changeset patch
# User Gregory Szorc <gregory.szorc at gmail.com>
# Date 1443825360 25200
#      Fri Oct 02 15:36:00 2015 -0700
# Node ID ba68484c8cb8d72f1b172af4d1f4771e8a71746c
# Parent  97dc6ab42aad232c73180dee648685c26662230b
exchange: add docstring to pull()

This seems like the kind of important function that should be documented
better.

diff --git a/mercurial/exchange.py b/mercurial/exchange.py
--- a/mercurial/exchange.py
+++ b/mercurial/exchange.py
@@ -916,8 +916,23 @@ class transactionmanager(object):
         if self._tr is not None:
             self._tr.release()
 
 def pull(repo, remote, heads=None, force=False, bookmarks=(), opargs=None):
+    """Fetch repository data from a remote.
+
+    This is the main function used to retrieve data from a remote repository.
+
+    ``repo`` is the local repository to clone into.
+    ``remote`` is a peer instance.
+    ``heads`` is an iterable of revisions we want to pull. ``None`` (the
+    default) means to pull everything from the remote.
+    ``bookmarks`` is an iterable of bookmarks requesting to be pulled. By
+    default, all remote bookmarks are pulled.
+    ``opargs`` are additional keyword arguments to pass to ``pulloperation``
+    initialization.
+
+    Returns the ``pulloperation`` created for this pull.
+    """
     if opargs is None:
         opargs = {}
     pullop = pulloperation(repo, remote, heads, force, bookmarks=bookmarks,
                            **opargs)