KCC: improve docstring and comments for KCC.load_site()

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 753d502226e79b9f956b8db341e781bbab6f0ac8..97d1618074c79347ac4a96144f71bee811f6d154 100755 (executable)
--- a/source4/scripting/bin/samba_kcc
+++ b/source4/scripting/bin/samba_kcc
@@ -167,14 +167,19 @@ class KCC(object):
             self.sitelink_table[dnstr] = sitelink
 
     def load_site(self, dn_str):
-        """Helper for load_my_site and load_all_sites. It puts all the site's
-        DSAs into the KCC indices.
+        """Helper for load_my_site and load_all_sites.
+
+        Put all the site's DSAs into the KCC indices.
+
+        :param dn_str: a site dn_str
+        :return: the Site object pertaining to the dn_str
         """
         site = Site(dn_str, unix_now)
         site.load_site(self.samdb)
 
-        # I am not sure why, but we avoid replacing the site with an
-        # identical copy.
+        # We avoid replacing the site with an identical copy in case
+        # somewhere else has a reference to the old one, which would
+        # lead to all manner of confusion and chaos.
         guid = str(site.site_guid)
         if guid not in self.site_table:
             self.site_table[guid] = site