[tor-commits] [bridgedb/master] Add docstring for bridgedb.Bridges.BridgeRing.insert().

[isis at torproject.org]

commit e64e9a588d320d8f4a22379f8c9082f5091ce147
Author: Isis Lovecruft <isis at torproject.org>
Date:   Sun Jan 12 01:12:49 2014 +0000

    Add docstring for bridgedb.Bridges.BridgeRing.insert().
---
 lib/bridgedb/Bridges.py |   15 +++++++++++++--
 1 file changed, 13 insertions(+), 2 deletions(-)

diff --git a/lib/bridgedb/Bridges.py b/lib/bridgedb/Bridges.py
index e293e40..93d945d 100644
--- a/lib/bridgedb/Bridges.py
+++ b/lib/bridgedb/Bridges.py
@@ -754,8 +754,19 @@ class BridgeRing(BridgeHolder):
             subring.clear()
 
     def insert(self, bridge):
-        """Add a bridge to the ring.  If the bridge is already there,
-           replace the old one."""
+        """Add a **bridge** to this hashring.
+
+        The bridge's position in the hashring is dependent upon the HMAC of
+        the raw hash digest of the bridge's ID key. The function used to
+        generate the HMAC, :ivar:`BridgeRing.hmac`, is unique to each
+        individual hashring.
+
+        If the (presumably same) bridge is already at that determined position
+        in this hashring, replace the old one.
+
+        :type bridge: :class:`~bridgedb.Bridges.Bridge`
+        :param bridge: The bridge to insert into this hashring.
+        """
         for tp,val,_,subring in self.subrings:
             if tp == 'port':
                 if val == bridge.orport: