[tor-commits] [bridgedb/master] Update docstring for bridgedb.runner.generateDescriptors().

[isis at torproject.org]

commit 5fff432beae935dd76443e86e064bfcad3f54335
Author: Isis Lovecruft <isis at torproject.org>
Date:   Tue Nov 5 08:41:56 2013 +0000

    Update docstring for bridgedb.runner.generateDescriptors().
---
 lib/bridgedb/runner.py |   24 +++++++++++++++++-------
 1 file changed, 17 insertions(+), 7 deletions(-)

diff --git a/lib/bridgedb/runner.py b/lib/bridgedb/runner.py
index b477c35..1f30dfb 100644
--- a/lib/bridgedb/runner.py
+++ b/lib/bridgedb/runner.py
@@ -22,13 +22,23 @@ import sys
 def generateDescriptors(count=None, rundir=None):
     """Run a script which creates fake bridge descriptors for testing purposes.
 
-    This will run scripts/gen_bridge_descriptors to create a bridge router
-    descriptors, bridge extrainfo descriptors, a consensus document, and a
-    networkstatus document.
-
-    :param integer howmany: Number of fake bridges to generate descriptor for.
-    :rtype: integer
-    :returns: The process returncode from the gen_bridge_descriptors script.
+    This will run ``scripts/gen_bridge_descriptors`` to create bridge server
+    descriptors, bridge extra-info descriptors, and networkstatus document.
+
+    ** NOTE: **
+        This function can take a very long time to run, especially in headless
+        environments where entropy sources are minimal, because it creates the
+        keys for each mocked OR, which are embedded in the server descriptors,
+        used to calculate the OR fingerprints, and sign the descriptors, among
+        other things.
+
+    :param integer count: Number of mocked bridges to generate descriptor
+        for. (default: 3)
+    :type rundir: string or None
+    :param rundir: If given, use this directory as the current working
+        directory for the bridge descriptor generator script to run in. The
+        directory MUST already exist, and the descriptor files will be created
+        in it. If None, use the whatever directory we are currently in.
     """
     import subprocess
     import os.path