D523: revset: improve documentation about ordering handling

[quark (Jun Wu)]

quark created this revision.
Herald added a subscriber: mercurial-devel.
Herald added a reviewer: hg-reviewers.

REVISION SUMMARY
  The old documentation is a bit confusing. Namely, it's unclear whether
  `define` means "I should ALWAYS define a new order", or "I should SOMETIMES
  define a new order", and if it's the latter, what's the difference between
  `define` and `any`?
  
  This patch clarifies that and adds more examples.

REPOSITORY
  rHG Mercurial

REVISION DETAIL
  https://phab.mercurial-scm.org/D523

AFFECTED FILES
  mercurial/revsetlang.py

CHANGE DETAILS

diff --git a/mercurial/revsetlang.py b/mercurial/revsetlang.py
--- a/mercurial/revsetlang.py
+++ b/mercurial/revsetlang.py
@@ -260,9 +260,10 @@
 
 # Constants for ordering requirement, used in getset():
 #
-# If 'define', any nested functions and operations can change the ordering of
-# the entries in the set. If 'follow', any nested functions and operations
-# should take the ordering specified by the first operand to the '&' operator.
+# If 'define', any nested functions and operations MAY change the ordering of
+# the entries in the set (but if changes the ordering, it MUST ALWAYS change
+# it). If 'follow', any nested functions and operations MUST take the ordering
+# specified by the first operand to the '&' operator.
 #
 # For instance,
 #
@@ -276,15 +277,28 @@
 #
 # 'any' means the order doesn't matter. For instance,
 #
-#   X & !Y
-#        ^
-#        any
+#   (X & Y) | ancestors(Z)
+#        ^              ^
+#        any            any
+#
+# For 'X & Y', 'X' decides order so the order of 'Y' does not matter. For
+# 'ancesotrs(Z)', Z's order does not matter since 'ancesotrs' does not care
+# about the order of its argument.
 #
-# 'y()' can either enforce its ordering requirement or take the ordering
-# specified by 'x()' because 'not()' doesn't care the order.
-anyorder = 'any'        # don't care the order
-defineorder = 'define'  # should define the order
-followorder = 'follow'  # must follow the current order
+# Currently, most revsets do not care about the order, so 'define' is
+# equivalent to 'follow' for them, and the resulting order is based on the
+# 'subset' parameter passed down to them:
+#
+#   m = revset.match(..., order=defineorder)
+#   m(repo, subset)
+#           ^^^^^^
+#      For most revsets, 'define' means using the order this subset provides
+#
+# There are a few revsets that always redefine the order if 'define' is
+# specified: 'sort(X)', 'reverse(X)', 'x:y'.
+anyorder = 'any'        # don't care the order, could be even random-shuffled
+defineorder = 'define'  # ALWAYS redefine, or ALWAYS follow the current order
+followorder = 'follow'  # MUST follow the current order
 
 def _matchonly(revs, bases):
     """



To: quark, #hg-reviewers
Cc: mercurial-devel