[tor-commits] [bridgedb/develop] Add docstring to `bridgedb.parse.descriptors.deduplicate()`.

[isis at torproject.org]

commit 72bb77e1d8336edd2e887711e59e1c499b7e0d16
Author: Isis Lovecruft <isis at torproject.org>
Date:   Tue Aug 26 03:59:34 2014 +0000

    Add docstring to `bridgedb.parse.descriptors.deduplicate()`.
---
 lib/bridgedb/parse/descriptors.py |   12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/lib/bridgedb/parse/descriptors.py b/lib/bridgedb/parse/descriptors.py
index 362731f..939ecb0 100644
--- a/lib/bridgedb/parse/descriptors.py
+++ b/lib/bridgedb/parse/descriptors.py
@@ -86,6 +86,18 @@ def parseServerDescriptorsFile(filename, validate=False):
     return routers
 
 def deduplicate(descriptors):
+    """Deduplicate some descriptors, returning only the newest for each router.
+
+    .. note:: If two descriptors for the same router are discovered, AND both
+        descriptors have the **same** published timestamp, then the router's
+        fingerprint WILL BE LOGGED ON PURPOSE, because we assume that router
+        to be malicious (deliberately, or unintentionally).
+
+    :param list descriptors: A list of
+        :api:`stem.descriptor.server_descriptor.RelayDescriptor`s,
+        :api:`stem.descriptor.extrainfo_descriptor.BridgeExtraInfoDescriptor`s,
+        :api:`stem.descriptor.router_status_entry.RouterStatusEntryV2`s.
+    """
     duplicates = []
     nonDuplicates = []