# HG changeset patch
# User Jun Wu <quark@fb.com>
# Date 1490885988 25200
# Node ID 17d0dab7b2b6829fdb91717378476bd29ec0b050
# Parent  985de02b5b9deaec6bcaaf14f3eadd2be9250904
revlog: clarify flagprocessor documentation

The words "text", "newtext", "bool" could be confusing. Use explicit "text"
or "rawtext" and document more about the "bool".

diff -r 985de02b5b9d -r 17d0dab7b2b6 mercurial/revlog.py
--- a/mercurial/revlog.py	Thu Mar 30 20:48:57 2017 -0700
+++ b/mercurial/revlog.py	Thu Mar 30 07:59:48 2017 -0700
@@ -88,11 +88,17 @@
     - Only one flag processor can be registered on a specific flag.
     - flagprocessors must be 3-tuples of functions (read, write, raw) with the
       following signatures:
-          - (read)  f(self, text) -> newtext, bool
-          - (write) f(self, text) -> newtext, bool
-          - (raw)   f(self, text) -> bool
+          - (read)  f(self, rawtext) -> text, bool
+          - (write) f(self, text) -> rawtext, bool
+          - (raw)   f(self, rawtext) -> bool
+      "text" is presented to the user. "rawtext" is stored in revlog data, not
+      directly visible to the user.
       The boolean returned by these transforms is used to determine whether
-      'newtext' can be used for hash integrity checking.
+      the returned text can be used for hash integrity checking. For example,
+      if "write" returns False, then "text" is used to generate hash. If
+      "write" returns True, that basically means "rawtext" returned by "write"
+      should be used to generate hash. Usually, "write" and "read" return
+      different booleans. And "raw" returns a same boolean as "write".
 
       Note: The 'raw' transform is used for changegroup generation and in some
       debug commands. In this case the transform only indicates whether the