setdiscovery: document the '_updatesample' function
This function is central in the sample building process, having it documented
help code readability a lot.
--- a/mercurial/setdiscovery.py Tue Jan 06 16:40:33 2015 -0800
+++ b/mercurial/setdiscovery.py Tue Jan 06 17:02:32 2015 -0800
@@ -46,6 +46,20 @@
import util, dagutil
def _updatesample(dag, nodes, sample, always, quicksamplesize=0):
+ """update an existing sample to match the expected size
+
+ The sample is updated with nodes exponentially distant from each head of the
+ <nodes> set. (H~1, H~2, H~4, H~8, etc).
+
+ If a target size is specified, the sampling will stop once this size is
+ reached. Otherwise sampling will happen until roots of the <nodes> set are
+ reached.
+
+ :dag: a dag object from dagutil
+ :nodes: set of nodes we want to discover (if None, assume the whole dag)
+ :sample: a sample to update
+ :always: set of notable nodes that will be part of the sample anyway
+ :quicksamplesize: optional target size of the sample"""
# if nodes is empty we scan the entire graph
if nodes:
heads = dag.headsetofconnecteds(nodes)