Patchwork [1,of,6,V3] obsolete: clarify documentation for succcessorssets

login
register
mail settings
Submitter Sean Farley
Date Jan. 16, 2014, 12:34 a.m.
Message ID <8d89a657625079b8c4e5.1389832456@laptop.local>
Download mbox | patch
Permalink /patch/3334/
State Superseded
Commit c05b968d05eb93762c81d628ea804478565a3015
Headers show

Comments

Sean Farley - Jan. 16, 2014, 12:34 a.m.
# HG changeset patch
# User Sean Farley <sean.michael.farley@gmail.com>
# Date 1389831252 21600
#      Wed Jan 15 18:14:12 2014 -0600
# Node ID 8d89a657625079b8c4e530a37d18b20de89c380e
# Parent  47d0843647d1e32f6af4482867327cec5db11a1f
obsolete: clarify documentation for succcessorssets
Pierre-Yves David - Jan. 16, 2014, 1:03 a.m.
On 01/15/2014 04:34 PM, Sean Farley wrote:
> # HG changeset patch
> # User Sean Farley <sean.michael.farley@gmail.com>
> # Date 1389831252 21600
> #      Wed Jan 15 18:14:12 2014 -0600
> # Node ID 8d89a657625079b8c4e530a37d18b20de89c380e
> # Parent  47d0843647d1e32f6af4482867327cec5db11a1f
> obsolete: clarify documentation for succcessorssets
>
> diff --git a/mercurial/obsolete.py b/mercurial/obsolete.py
> --- a/mercurial/obsolete.py
> +++ b/mercurial/obsolete.py
> @@ -507,33 +507,41 @@ def foreground(repo, nodes):
>   
>   
>   def successorssets(repo, initialnode, cache=None):
>       """Return all set of successors of initial nodes
>   
> -    Successors set of changeset A are a group of revision that succeed A. It
> -    succeed A as a consistent whole, each revision being only partial
> -    replacement.  Successors set contains non-obsolete changeset only.
> +    The successors set of a changeset A are a group of revisions that succeed
> +    A. It succeed A as a consistent whole, each revision being only partial
> +    replacement.  The successors set contains non-obsolete changeset only.

We could highlight here that the function returns the full list of 
successors sets, that is why we have a list of tuple and not just a tuple.

>   
> -    In most cases a changeset A have zero (changeset pruned) or a single
> -    successors set that contains a single successor (changeset A replaced by
> -    A')
> +    In most cases a changeset A will have zero (e.g. the changeset pruned)
> +    elements in its successors set or a successors set that contains a single
> +    element (e.g. changeset A replaced by A'). Therefor, these successors sets
> +    will look like [()] or [(A',)], respectively.

Fun fact: pruned changeset actually returns `[]` (not `[()]`). You 
should not trust what people tell you on the internet ;-)

>   
> -    When changeset is split, it results successors set containing more than
> -    a single element. Divergent rewriting will result in multiple successors
> -    sets.
> +    When changeset A is split into A' and B', however, it will result in a
> +    successors set containing more than a single element, i.e. [(A',B')].
> +    Divergent changesets will result in multiple successors sets, i.e. [(A',),
> +    (A'')].
> +
> +    If a changeset A is not obsolete, then it will conceptually have no
> +    successors set.  To distinguish this from a pruned changeset, the successor
> +    set will only contain itself, i.e. [(A,)].
>   
>       They are returned as a list of tuples containing all valid successors sets.
>   
> -    Final successors unknown locally are considered plain prune (obsoleted
> +    Finally, successors unknown locally are considered plain prune (obsoleted
>       without successors).
>   
> -    The optional `cache` parameter is a dictionary that may contains
> -    precomputed successors sets. It is meant to reuse the computation of
> -    previous call to `successorssets` when multiple calls are made at the same
> -    time. The cache dictionary is updated in place. The caller is responsible
> -    for its live spawn. Code that makes multiple calls to `successorssets`
> -    *must* use this cache mechanism or suffer terrible performances."""
> +    The optional `cache` parameter is a dictionary that may contain precomputed
> +    successors sets. It is meant to reuse the computation of a previous call to
> +    `successorssets` when multiple calls are made at the same time. The cache
> +    dictionary is updated in place. The caller is responsible for its live
> +    spawn. Code that makes multiple calls to `successorssets` *must* use this
> +    cache mechanism or suffer terrible performances.
> +
> +    """
>

The rest is fine.

Patch

diff --git a/mercurial/obsolete.py b/mercurial/obsolete.py
--- a/mercurial/obsolete.py
+++ b/mercurial/obsolete.py
@@ -507,33 +507,41 @@  def foreground(repo, nodes):
 
 
 def successorssets(repo, initialnode, cache=None):
     """Return all set of successors of initial nodes
 
-    Successors set of changeset A are a group of revision that succeed A. It
-    succeed A as a consistent whole, each revision being only partial
-    replacement.  Successors set contains non-obsolete changeset only.
+    The successors set of a changeset A are a group of revisions that succeed
+    A. It succeed A as a consistent whole, each revision being only partial
+    replacement.  The successors set contains non-obsolete changeset only.
 
-    In most cases a changeset A have zero (changeset pruned) or a single
-    successors set that contains a single successor (changeset A replaced by
-    A')
+    In most cases a changeset A will have zero (e.g. the changeset pruned)
+    elements in its successors set or a successors set that contains a single
+    element (e.g. changeset A replaced by A'). Therefor, these successors sets
+    will look like [()] or [(A',)], respectively.
 
-    When changeset is split, it results successors set containing more than
-    a single element. Divergent rewriting will result in multiple successors
-    sets.
+    When changeset A is split into A' and B', however, it will result in a
+    successors set containing more than a single element, i.e. [(A',B')].
+    Divergent changesets will result in multiple successors sets, i.e. [(A',),
+    (A'')].
+
+    If a changeset A is not obsolete, then it will conceptually have no
+    successors set.  To distinguish this from a pruned changeset, the successor
+    set will only contain itself, i.e. [(A,)].
 
     They are returned as a list of tuples containing all valid successors sets.
 
-    Final successors unknown locally are considered plain prune (obsoleted
+    Finally, successors unknown locally are considered plain prune (obsoleted
     without successors).
 
-    The optional `cache` parameter is a dictionary that may contains
-    precomputed successors sets. It is meant to reuse the computation of
-    previous call to `successorssets` when multiple calls are made at the same
-    time. The cache dictionary is updated in place. The caller is responsible
-    for its live spawn. Code that makes multiple calls to `successorssets`
-    *must* use this cache mechanism or suffer terrible performances."""
+    The optional `cache` parameter is a dictionary that may contain precomputed
+    successors sets. It is meant to reuse the computation of a previous call to
+    `successorssets` when multiple calls are made at the same time. The cache
+    dictionary is updated in place. The caller is responsible for its live
+    spawn. Code that makes multiple calls to `successorssets` *must* use this
+    cache mechanism or suffer terrible performances.
+
+    """
 
     succmarkers = repo.obsstore.successors
 
     # Stack of nodes we search successors sets for
     toproceed = [initialnode]