[PATCH 1 of 6 V3] obsolete: clarify documentation for succcessorssets
Pierre-Yves David
pierre-yves.david at ens-lyon.org
Wed Jan 15 19:03:02 CST 2014
On 01/15/2014 04:34 PM, Sean Farley wrote:
> # HG changeset patch
> # User Sean Farley <sean.michael.farley at 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.
--
Pierre-Yves
More information about the Mercurial-devel
mailing list