# HG changeset patch
# User Pierre-Yves David <pierre-yves.david@fb.com>
# Date 2014-03-14 17:57:04
# Node ID 1b4f2399f3c4b3036121a0f3b3089012623c0d4c
# Parent  33943add5d6557af935e0ff8f910f9f5dc8be5ae

revset: add documentation and comment for _generatorset

(clean up some old irrelevant comment in the process)

diff --git a/mercurial/revset.py b/mercurial/revset.py
--- a/mercurial/revset.py
+++ b/mercurial/revset.py
@@ -2554,6 +2554,9 @@ class _generatorset(object):
     internally
     """
     def __init__(self, gen):
+        """
+        gen: a generator producing the values for the generatorset.
+        """
         self._gen = gen
         self._iter = iter(gen)
         self._cache = {}
@@ -2565,6 +2568,7 @@ class _generatorset(object):
         if x in self._cache:
             return self._cache[x]
 
+        # Use __iter__ which caches values and stores them into self._genlist
         for l in self:
             if l == x:
                 return True
@@ -2575,9 +2579,12 @@ class _generatorset(object):
 
     def __iter__(self):
         if self._iterated:
+            # At least a part of the list should be cached if iteration has
+            # started over the generatorset.
             for l in self._genlist:
                 yield l
         else:
+            # Starting iteration over the generatorset.
             self._iterated = True
 
         for item in self._gen:
@@ -2585,13 +2592,14 @@ class _generatorset(object):
             self._genlist.append(item)
             yield item
 
+        # Iteration over the generator has finished. Whole value list should be
+        # cached in self._genlist
         self._finished = True
 
     def set(self):
         return self
 
     def sort(self, reverse=False):
-        # Basic implementation to be changed in future patches
         if not self._finished:
             for i in self:
                 continue