From patchwork Mon Jun 27 13:43:16 2016
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Subject: [5,of,8] scmutil: improve documentation of revset APIs
From: Pulkit Goyal <7895pulkit@gmail.com>
X-Patchwork-Id: 15640
Message-Id: <8362c2e98584b12f4925.1467034996@pulkit-goyal>
To: mercurial-devel@mercurial-scm.org
Date: Mon, 27 Jun 2016 19:13:16 +0530

# HG changeset patch
# User Gregory Szorc <gregory.szorc@gmail.com>
# Date 1466907140 25200
#      Sat Jun 25 19:12:20 2016 -0700
# Node ID 8362c2e98584b12f4925580dfe80853179f755b7
# Parent  7a1ddd9404b6290fa06e3df56b53ab9f9567b591
scmutil: improve documentation of revset APIs

I can never remember the differences between the various revset
APIs. I can never remember that scmutil.revrange() is the one I
want to use from user-facing commands.

Add some documentation to clarify this.

While we're here, the argument name for revrange() is changed to
"specs" because that's what it actually is.

diff -r 7a1ddd9404b6 -r 8362c2e98584 mercurial/localrepo.py
--- a/mercurial/localrepo.py	Sat Jun 25 13:52:46 2016 -0700
+++ b/mercurial/localrepo.py	Sat Jun 25 19:12:20 2016 -0700
@@ -554,7 +554,10 @@
         The revset is specified as a string ``expr`` that may contain
         %-formatting to escape certain types. See ``revset.formatspec``.
 
-        Return a revset.abstractsmartset, which is a list-like interface
+        Revset aliases from the configuration are not expanded. To expand
+        user aliases, consider calling ``scmutil.revrange()``.
+
+        Returns a revset.abstractsmartset, which is a list-like interface
         that contains integer revisions.
         '''
         expr = revset.formatspec(expr, *args)
@@ -566,6 +569,9 @@
 
         This is a convenience wrapper around ``revs()`` that iterates the
         result and is a generator of changectx instances.
+
+        Revset aliases from the configuration are not expanded. To expand
+        user aliases, consider calling ``scmutil.revrange()``.
         '''
         for r in self.revs(expr, *args):
             yield self[r]
diff -r 7a1ddd9404b6 -r 8362c2e98584 mercurial/scmutil.py
--- a/mercurial/scmutil.py	Sat Jun 25 13:52:46 2016 -0700
+++ b/mercurial/scmutil.py	Sat Jun 25 19:12:20 2016 -0700
@@ -808,10 +808,29 @@
 
     return repo.lookup(first), repo.lookup(second)
 
-def revrange(repo, revs):
-    """Yield revision as strings from a list of revision specifications."""
+def revrange(repo, specs):
+    """Execute 1 to many revsets and return the union.
+
+    This is the preferred mechanism for executing revsets using user-specified
+    config options, such as revset aliases.
+
+    The revsets specified by ``specs`` will be executed via a chained ``OR``
+    expression. If ``specs`` is empty, an empty result is returned.
+
+    ``specs`` can contain integers, in which case they are assumed to be
+    revision numbers.
+
+    It is assumed the revsets are already formatted. If you have arguments
+    that need to be expanded in the revset, call ``revset.formatspec()``
+    and pass the result as an element of ``specs``.
+
+    Specifying a single revset is allowed.
+
+    Returns a ``revset.abstractsmartset`` which is a list-like interface over
+    integer revisions.
+    """
     allspecs = []
-    for spec in revs:
+    for spec in specs:
         if isinstance(spec, int):
             spec = revset.formatspec('rev(%d)', spec)
         allspecs.append(spec)