KCC: improve docstring for KCC.is_stale_link_connection()

Signed-off-by: Douglas Bagnall <douglas.bagnall@catalyst.net.nz>
Reviewed-by: Garming Sam <garming@catalyst.net.nz>
Reviewed-by: Andrew Bartlett <abartlet@samba.org>

diff --git a/source4/scripting/bin/samba_kcc b/source4/scripting/bin/samba_kcc
index 0100149c510f597e6ad2acd750747af75d18bf09..5d670c040ce0ed253df62a8e7526ae5762c96c87 100755 (executable)
--- a/source4/scripting/bin/samba_kcc
+++ b/source4/scripting/bin/samba_kcc
@@ -369,12 +369,16 @@ class KCC(object):
         self.kcc_failed_connections.difference_update(restore_connections)
 
     def is_stale_link_connection(self, target_dsa):
-        """Returns False if no tuple z exists in the kCCFailedLinks or
-        kCCFailedConnections variables such that z.UUIDDsa is the
-        objectGUID of the target dsa, z.FailureCount > 0, and
-        the current time - z.TimeFirstFailure > 2 hours.
+        """Check whether a link to a remote DSA is stale
+
+        Used in MS-ADTS 6.2.2.2 Intrasite Connection Creation
+
+        Returns True if the remote seems to have been down for at
+        least two hours, otherwise False.
+
+        :param target_dsa: the remote DSA object
+        :return: True if link is stale, otherwise False
         """
-        # Returns True if tuple z exists...
         failed_link = self.kcc_failed_links.get(str(target_dsa.dsa_guid))
         if failed_link:
             # failure_count should be > 0, but check anyways